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Introduction 


I have a confession to make. The first time I ever heard of OpenGL was at the 1992 Win32 
Developers Conference in San Francisco. Windows NT 3.1 was in early beta (or late alpha), 
and many vendors were present, pledging their future support for this exciting new graph- 
ics technology. Among them was a company called Silicon Graphics, Inc. (SGI). The SGI 
representatives were showing off their graphics workstations and playing video demos of 
special effects from some popular movies. Their primary purpose in this booth, however, 
was to promote a new 3D graphics standard called OpenGL. It was based on SGI's propri- 
etary IRIS GL and was fresh out of the box as a graphics standard. Significantly, Microsoft 
was pledging future support for OpenGL in Windows NT. 


I had to wait until the beta release of NT 3.5 before I got my first personal taste of 
OpenGL. Those first OpenGL-based screensavers only scratched the surface of what was 
possible with this graphics API. Like many other people, I struggled through the Microsoft 
help files and bought a copy of the OpenGL Programming Guide (now called simply “The 
Red Book” by most). The Red Book was not a primer, however, and it assumed a lot of 
knowledge that I just didn’t have. 


Now for that confession I promised. How did I learn OpenGL? I learned it by writing a 
book about it. That’s right, the first edition of the OpenGL SuperBible was me learning how 
to do 3D graphics myself...with a deadline! Somehow I pulled it off, and in 1996 the first 
edition of the book you are holding was born. Teaching myself OpenGL from scratch 
enabled me somehow to better explain the API to others in a manner that a lot of people 
seemed to like. The whole project was nearly canceled when Waite Group Press was 
acquired by another publisher halfway through the publishing process. Mitchell Waite 
stuck to his guns and insisted that OpenGL was going to be “the next big thing” in 
computer graphics. Vindication arrived when an emergency reprint was required because 
the first run of the book sold out before ever making it to the warehouse. 


That was a long time ago, and in what seems like a galaxy far, far away... 


Only three years later 3D accelerated graphics were a staple for even the most stripped- 
down PCs. The “API Wars,” a political battle between Microsoft and SGI, had come and 
gone; OpenGL was firmly established in the PC world; and 3D hardware acceleration was 
as common as CD-ROMs and sound cards. I had even managed to turn my career more 
toward an OpenGL orientation and had the privilege of contributing in some small ways 
to the OpenGL specification for version 1.2 while working at Lockheed Martin/Real 3D. 
The second edition of this book, released at the end of 1999, was significantly expanded 
and corrected. We even made some modest initial attempts to ensure all the sample 
programs were more friendly in non-Windows platforms by using the GLUT framework. 
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Now, nearly five years later (eight since the first edition!), we bring you yet again another 
edition, the third, of this book. OpenGL is now without question the premier cross- 
platform real-time 3D graphics API. Excellent OpenGL stability and performance are avail- 
able on even the most stripped-down bargain PC today. OpenGL is also the standard for 
UNIX and Linux operating systems, and Apple has made OpenGL a core fundamental 
technology for the new MacOS X operating system. OpenGL is even making inroads via a 
new specification, OpenGL ES, into embedded and mobile spaces. Who would have 
thought five years ago that we would see Quake running on a cell phone? 


It is exciting that, today, even laptops have 3D acceleration, and OpenGL is truly every- 
where and on every mainstream computing platform. Even more exciting, however, is the 
continuing evolution of computer graphics hardware. Today, most graphics hardware is 
programmable, and OpenGL even has its own shading language, which can produce stun- 
ningly realistic graphics that were undreamed of on commodity hardware back in the last 
century. (I just had to squeeze that in someplace!) 


With this third edition, I am pleased that we have added Benjamin Lipchak as a coauthor. 

Benj is primarily responsible for the chapters that deal with OpenGL shader programs, and 
coming from the ARB groups responsible for this aspect of OpenGL, he is one of the most 

qualified authors on this topic in the world. 


We have also fully left behind the “Microsoft Specific” characteristics of the first edition 
and have embraced a more multiplatform approach. All the programming examples in this 
book have been tested on Windows, MacOS X, and at least one version of Linux. There is 
even one chapter apiece on these operating systems, with information about using 
OpenGL with native applications. 


What's in This Book 


The OpenGL SuperBible is divided into three parts. In the first, we cover what we call Classic 
OpenGL. This is the fixed pipeline functionality that has been a characteristic of OpenGL 
from the beginning. Many of these chapters have been greatly expanded since the second 
edition because OpenGL has had a number of revisions since version 1.2. Fixed pipeline 
programming will still be with us for a long time to come, and its simple programming 
model will still make it the choice of many programmers for years. 


In these chapters, you will learn the fundamentals of real-time 3D graphics programming 
with OpenGL. You'll learn how to construct a program that uses OpenGL, how to set up 
your 3D-rendering environment, and how to create basic objects and light and shade 
them. Then we'll delve deeper into using OpenGL and some of its advanced features and 
different special effects. These chapters are a good way to introduce yourself to 3D graph- 
ics programming with OpenGL and provide the conceptual foundation on which the more 
advanced capabilities later in the book are based. 


Introduction 


In the second part, three chapters provide specific information about using OpenGL on 
the three mainstream operating system families: Windows, MacOS X, and Linux/UNIX. 


Finally, the third part contains the newest features not just of OpenGL, but of 3D graphics 
hardware in general today. The OpenGL Shading Language, in particular, is the principal 
feature of OpenGL 2.0, and it represents the biggest advance in computer graphics in 
many years. 


Part |: Classic OpenGL 
Chapter 1—Introduction to 3D Graphics and OpenGL 


This introductory chapter is for newcomers to 3D graphics. It introduces fundamental 
concepts and some common vocabulary. 


Chapter 2—Using OpenGL 


In this chapter, we provide you with a working knowledge of what OpenGL is, where it 
came from, and where it is going. You will write your first program using OpenGL, find 
out what headers and libraries you need to use, learn how to set up your environment, 
and discover how some common conventions can help you remember OpenGL function 
calls. We also introduce the OpenGL state machine and error-handling mechanism. 


Chapter 3—Drawing in Space: Geometric Primitives and Buffers 


Here, we present the building blocks of 3D graphics programming. You'll basically find 
out how to tell a computer to create a three-dimensional object with OpenGL. You'll also 
learn the basics of hidden surface removal and ways to use the stencil buffer. 


Chapter 4—Geometric Transformations: The Pipeline 


Now that you’re creating three-dimensional shapes in a virtual world, how do you move 
them around? How do you move yourself around? These are the things you’ll learn here. 


Chapter 5—Color, Materials, and Lighting: The Basics 


In this chapter, you'll take your three-dimensional “outlines” and give them color. You'll 
learn how to apply material effects and lights to your graphics to make them look real. 


Chapter 6—More on Colors and Materials 


Now it’s time to learn about blending objects with the background to make transparent 
(see-through) objects. You’ll also learn some special effects with fog and the accumulation 
buffer. 


Chapter 7—Imaging with OpenGL 


This chapter is all about manipulating image data within OpenGL. This information 
includes reading a TGA file and displaying it in an OpenGL window. You'll also learn 
some powerful OpenGL image-processing capabilities. 
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Chapter 8—Texture Mapping: The Basics 


Texture mapping is one of the most useful features of any 3D graphics toolkit. You'll learn 
how to wrap images onto polygons and how to load and manage multiple textures at 
once. 


Chapter 9—Texture Mapping: Beyond the Basics 


In this chapter, you'll learn how to generate texture coordinates automatically, use 
advanced filtering modes, and use built-in hardware support for texture compression. 
You'll also learn about OpenGL’s powerful texture combiner functionality. 


Chapter 10—Curves and Surfaces 


The simple triangle is a powerful building block. This chapter gives you some tools for 
manipulating the mighty triangle. You'll learn about some of OpenGL’s built-in quadric 
surface generation functions and ways to use automatic tessellation to break complex 
shapes into smaller, more digestible pieces. You'll also explore the utility functions that 
evaluate Bézier and NURBS curves and surfaces. You can use these functions to create 
complex shapes with an amazingly small amount of code. 


Chapter 11—It’s All About the Pipeline: Faster Geometry Throughput 


For this chapter, we show you how to build complex 3D objects out of smaller, less 
complex 3D objects. We introduce OpenGL display lists and vertex arrays for improving 
performance and organizing your models. You’ll also learn how to create a detailed analy- 
sis showing how to best represent large, complex models. 


Chapter 12—Interactive Graphics 


This chapter explains two OpenGL features: selection and feedback. These groups of func- 
tions make it possible for the user to interact with objects in the scene. You can also get 
rendering details about any single object in the scene. 


Part Il: OpenGL Everywhere 
Chapter 13—Wiggle: OpenGL on Windows 
Here, you'll learn how to write real Windows (message-based) programs that use OpenGL. 


You'll learn about Microsoft's “wiggle” functions that glue OpenGL rendering code to 
Windows device contexts. You’ll also learn how to respond to Windows messages. 


Chapter 14—OpenGL on the MacOS X 


In this chapter, you'll learn how to use OpenGL in native MacOS X applications. Sample 
programs show you how to start working in Carbon or Cocoa using the Xcode develop- 
ment environment. 
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Chapter 15—GLX: OpenGL on Linux 


This chapter discusses GLX, the OpenGL extension used to support OpenGL applications 
through the X Window System on Unix and Linux. You'll learn how to create and manage 
OpenGL contexts as well as how to create OpenGL drawing areas with several of the 
common GUI toolkits. 


Part Ill: OpenGL: The Next Generation 
Chapter 16—Buffer Objects: It’s Your Video Memory; You Manage It! 


In this chapter, you’ll learn about OpenGL 1.5’s vertex buffer object feature. Buffer objects 
allow you to store vertex array data in memory that can be more efficiently accessed by 
the GPU, such as local VRAM or AGP-mapped system memory. 


Chapter 17—Occlusion Queries: Why Do More Work Than You Need To? 


Here, you'll learn about OpenGL 1.5’s occlusion query mechanism. This feature effectively 
lets you perform an inexpensive test-render of objects in your scene to find out whether 
they will be hidden behind other objects, in which case you can save time by not drawing 
the actual full-detail version. 


Chapter 18—Depth Textures and Shadows 


This chapter covers OpenGL 1.4’s depth textures and shadow comparisons. You'll learn 
how to introduce real-time shadow effects to your scene, regardless of the geometry’s 
complexity. 


Chapter 19—Programmable Pipeline: This Isn’t Your Father’s OpenGL 


Out with the old, in with the new. This chapter revisits the conventional fixed functional- 
ity pipeline before introducing the new programmable vertex and fragment pipeline 
stages. Programmability allows you to customize your rendering in ways never before 
possible using shader programs. 


Chapter 20—Low-Level Shading: Coding to the Metal 


In this chapter, you’ll learn about the low-level shader extensions: ARB_vertex_program and 
ARB_fragment_program. You can use them to customize your rendering via shader programs 
in a language reminiscent of assembly code, offering full control over the underlying 
hardware. 


Chapter 21—High-Level Shading: The Real Slim Shader 


Here, we discuss the OpenGL Shading Language, the high-level counterpart to the low- 
level extensions. GLSL is a C-like language that gives you increased functionality and 
productivity. 


OpenGL Super Bible 


Chapter 22—Vertex Shading: Do-It-Yourself Transform, Lighting, and Texgen 


This chapter illustrates the usage of vertex shaders by surveying a handful of examples, 
including lighting, fog, squash and stretch, and skinning. 


Chapter 23—Fragment Shading: Empower Your Pixel Processing 


Again, you learn by example—this time with a variety of fragment shaders. Examples 
include per-pixel lighting, color conversion, image processing, and procedural texturing. 
Some of these examples also use vertex shaders; these examples are representative of real- 
world usage, where you often find vertex and fragment shaders paired together. 


Conventions Used in This Book 
The following typographic conventions are used in this book: 


¢ Code lines, commands, statements, variables, and any text you type or see onscreen 
appear in a computer typeface. 


¢ Placeholders in syntax descriptions appear in an italic computer typeface. Replace 
the placeholder with the actual filename, parameter, or whatever element it repre- 
sents. 


¢ Italics highlight technical terms when they first appear in the text and are being 
defined. 


About the Companion CD 

The CD that comes with the OpenGL SuperBible is packed with sample programs, toolkits, 
source code, and documentation—everything but the kitchen sink! We dig up stuff to put 
on this CD all the way until press time, so check out the readme.txt file in the root of the 
CD for a complete list of all the goodies we include. 


The CD contains some basic organization. Off the root directory, you’ll find 


\Examples—Beneath this directory, you'll find a directory for each chapter in the book that has 
programming examples. Each sample has a real name (as opposed to sample 5.2c), so you can 
browse the CD with ease and run anything that looks interesting when you first get the book. 


\Tools—A collection of third-party tools and libraries appears here. Each has its own subdirectory 
and documentation from the original vendor. Sample programs throughout the book use some of 
these tools (GLUT in particular). 

\Demos—This directory contains a collection of OpenGL demo programs. These programs all show- 
case the rendering capabilities of OpenGL. Some are free; some are commercial demos. 
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For support issues with the CD, please contact Sams Publishing 
(www. samspublishing.com). Other OpenGL questions, more samples and tutorials, and, of 
course, the inevitable list of errata are posted on the book’s Web site at 


http://www. starstonesoftware.com/OpenGL 


Building the Sample Programs 

All the sample programs in this book are written in C. They should be easy to move to 
C++ for those so inclined, but C usually provides a larger audience for a book such as this, 
and is readily understood by anyone who might prefer C++. Most programs also use the 
g1Tools library, which is simply a collection of OpenGL-friendly utility functions written 
by the authors. The g1Tools header file (gltools.h) and source .c files are listed in the 
\common directory beneath the \Examples directories on the CD. 


Beneath \Examples, you will find a directory for each OS platform supported. Windows 
project files are written in Visual C++ 6.0. The reason is that many have chosen not to 
upgrade to the new .NET-biased version of the tools, and those who have (myself included 
on many projects) can easily import the projects. 


MacOS X sample project files were made with Xcode version 1.1. Anyone still using 
Project Builder should upgrade...it’s free, and it will add years to your life. All Mac samples 
were tested on OS X version 10.3.3. At the time of printing, Apple had not released drivers 
that support the OpenGL shading language. Latent Mac bugs could show up when it does. 
Check the Web site referenced in the preceding section for any necessary updates. 


Linux make files are also provided. There are 10,392,444,224,229,349,244,281,999.4 differ- 
ent ways to configure a Linux environment. Well, maybe not quite that many. Without 
meaning to sound too harsh, you are pretty much on your own. Because Xcode uses a 
similar gnu compiler that many Linux environments use, you shouldn’t have too many 
problems. I expect some additional notes and tutorials will show up on the book’s Web 
site over time. 


Dare to Dream in 3D! 


Once upon a time in the early 1980s, I was looking at a computer at an electronics store. 
The salesman approached and began making his pitch. I told him I was just learning to 
program and considering an Amiga over his model. I was briskly informed that I needed 
to get serious with a computer that the rest of the world was using. An Amiga, he told me, 
was not good for anything but “making pretty pictures.” No one, he assured me, could 
make a living making pretty pictures on his computer. 


This was possibly the worst advice I have ever received in the history of bad advice. A few 
years ago, I forgot about being a “respectable” database/enterprise/yada-yada-yada devel- 
oper. Now I write cool graphics programs, teach graphics programming, own my own 
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software company, and generally have more fun with my career than should probably be 
allowed by law! 


I hope I can give you some better advice today. Whether you want to write games, create 
military simulations, develop scientific visualizations, or visualize large corporate data- 
bases, OpenGL is the perfect API. It will meet you where you are as a beginner, and it will 
empower you when you become your own 3D guru. And yes, my friend, you can make a 
living making pretty pictures with your computer! 


—Richard S. Wright, Jr. 


PART | 
Classic OpenGL 


The following 12 chapters are about fixed pipeline 3D graphics 
rendering. In recent years, hardware on the PC platform has 
become quite mature, and sophisticated real-time graphics 
have become commonplace. The basic approach has not 
changed. We are still playing connect the dots and using trian- 
gles to make solid geometry. Performance now can be over- 
whelming, but by using the techniques in Part I of this book, 
you can create high-performance and stunning 3D graphics 
effects. 


Although many advanced, sophisticated effects are built on the 
more flexible capabilities explored in Part III, “OpenGL: The 
Next Generation,” the fixed pipeline capabilities of OpenGL 
remain the bedrock on which all else is built. We know that 
dedicated hardware is usually faster than flexible programma- 
ble hardware, and we can expect that for basic rendering needs 
the fixed pipeline functionality of OpenGL will remain with us 
for some time. 


CHAPTER 1 


Introduction to 3D Graphics 
and OpenGL 


by Richard S. Wright, Jr. 


What’s This All About? 


This book is about OpenGL, a programming interface for creating real-time 3D graphics. 
Before we begin talking about what OpenGL is and how it works, you should have at least 
a high-level understanding of real-time 3D graphics in general. Perhaps you picked up this 
book because you want to learn to use OpenGL, but you already have a good grasp of real- 
time 3D principles. If so, great: Skip directly to Chapter 2, “Using OpenGL.” If you bought 
this book because the pictures look cool and you want to learn how to do this on your 
PC...you should probably start here. 


A Brief History of Computer Graphics 


The first computers consisted of rows and rows of switches and lights. Technicians and 
engineers worked for hours, days, or even weeks to program these machines and read the 
results of their calculations. Patterns of illuminated bulbs conveyed useful information to 
the computer users, or some crude printout was provided. You might say that the first 
form of computer graphics was a panel of blinking lights. (This idea is supported by stories 
of early programmers writing programs that served no useful purpose other than creating 
patterns of blinking and chasing lights!) 


Times have changed. From those first “thinking machines,” as some called them, sprang 
fully programmable devices that printed on rolls of paper using a mechanism similar to a 
teletype machine. Data could be stored efficiently on magnetic tape, on disk, or even on 
rows of hole-punched paper or stacks of paper-punch cards. The “hobby” of computer 
graphics was born the day computers first started printing. Because each character in the 
alphabet had a fixed size and shape, creative programmers in the 1970s took delight in 
creating artistic patterns and images made up of nothing more than asterisks (*). 
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Enter the CRT 

Paper as an output medium for computers is useful and persists today. Laser printers and 
color inkjet printers have replaced crude ASCII art with crisp presentation quality and near 
photographic reproductions of artwork. Paper, however, can be expensive to replace on a 
regular basis, and using it consistently is wasteful of our natural resources, especially 
because most of the time we don’t really need hard-copy output of calculations or data- 
base queries. 


The cathode ray tube (CRT) was a tremendously useful addition to the computer. The orig- 
inal computer monitors, CRTs were initially just video terminals that displayed ASCII text 
just like the first paper terminals—but CRTs were perfectly capable of drawing points and 
lines as well as alphabetic characters. Soon, other symbols and graphics began to supple- 
ment the character terminal. Programmers used computers and their monitors to create 
graphics that supplemented textual or tabular output. The first algorithms for creating 
lines and curves were developed and published; computer graphics became a science 
rather than a pastime. 


The first computer graphics displayed on these terminals were two-dimensional, or 2D. 
These flat lines, circles, and polygons were used to create graphics for a variety of 
purposes. Graphs and plots could display scientific or statistical data in a way that tables 
and figures could not. More adventurous programmers even created simple arcade games 
such as Lunar Lander and Pong using simple graphics consisting of little more than line 
drawings that were refreshed (redrawn) several times a second. 


The term real-time was first applied to computer graphics that were animated. A broader 
use of the word in computer science simply means that the computer can process input as 
fast or faster than the input is being supplied. For example, talking on the phone is a real- 
time activity in which humans participate. You speak and the listener hears your commu- 
nication immediately and responds, allowing you to hear immediately and respond again, 
and so on. In reality, there is some delay involved due to the electronics, but the delay is 
usually imperceptible to those having the conversation. In contrast, writing a letter is not 
a real-time activity. 


Applying the term real-time to computer graphics means that the computer is producing 
an animation or sequence of images directly in response to some input, such as joystick 
movement, keyboard strokes, and so on. Real-time computer graphics can display a wave 
form being measured by electronic equipment, numerical readouts, or interactive games 
and visual simulations. 


Going 3D 

The term three-dimensional, or 3D, means that an object being described or displayed has 
three dimensions of measurement: width, height, and depth. An example of a two- 
dimensional object is a piece of paper on your desk with a drawing or writing on it, 
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having no perceptible depth. A three-dimensional object is the can of soda next to it. The 
soft drink can is round (width and height) and tall (depth). Depending on your perspec- 
tive, you can alter which side of the can is the width or height, but the fact remains that 
the can has three dimensions. Figure 1.1 shows how we might measure the dimensions of 
the can and piece of paper. 


FIGURE 1.1 Measuring two- and three-dimensional objects. 


For centuries, artists have known how to make a painting appear to have real depth. A 
painting is inherently a two-dimensional object because it is nothing more than canvas 
with paint applied. Similarly, 3D computer graphics are actually two-dimensional images 
on a flat computer screen that provide an illusion of depth, or a third dimension. 


2D + Perspective = 3D 

The first computer graphics no doubt appeared similar to Figure 1.2, where you can see a 
simple three-dimensional cube drawn with 12 line segments. What makes the cube look 
three-dimensional is perspective, or the angle between the lines that lend the illusion of 
depth. 


To truly see in 3D, you need to actually view an object with both eyes or supply each eye 
with separate and unique images of the object. Look at Figure 1.3. Each eye receives a two- 
dimensional image that is much like a temporary photograph displayed on each retina 
(the back part of your eye). These two images are slightly different because they are 
received at two different angles. (Your eyes are spaced apart on purpose.) The brain then 
combines these slightly different images to produce a single, composite 3D picture in your 
head. 


FIGURE 1.2 A simple wireframe 3D cube. 
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Retina image | Retina image 2 


FIGURE 1.3 How you see three dimensions. 


In Figure 1.3, the angle between the images becomes smaller as the object goes farther 
away. You can amplify this 3D effect by increasing the angle between the two images. 
Viewmasters (those hand-held stereoscopic viewers you probably had as a kid) and 3D 
movies capitalize on this effect by placing each of your eyes on a separate lens or by 
providing color-filtered glasses that separate two superimposed images. These images are 
usually over-enhanced for dramatic or cinematic purposes. Of late this effect has become 
more popular on the PC as well. Shutter glasses that work with your graphics card and 
software will switch between one eye and the other, with a changing perspective displayed 
onscreen to each eye, thus giving a “true” stereo 3D experience. Unfortunately, many 
people complain that this effect gives them a headache or makes them dizzy! 


A computer screen is one flat image on a flat surface, not two images from different 
perspectives falling on each eye. As it turns out, most of what is considered to be 3D 
computer graphics is actually an approximation of true 3D. This approximation is 
achieved in the same way that artists have rendered drawings with apparent depth for 
years, using the same tricks that nature provides for people with one eye. 


You might have noticed at some time in your life that if you cover one eye, the world does 
not suddenly fall flat! What happens when you cover one eye? You might think you are 
still seeing in 3D, but try this experiment: Place a glass or some other object just out of 
arm’s reach, off to your left side. (If it is close, this trick won’t work.) Cover your right eye 
with your right hand and reach for the glass. (Maybe you should use an empty plastic 
one!) Notice that you have a more difficult time estimating how much farther you need to 
reach (if at all) before you touch the glass. Now, uncover your right eye and reach for the 
glass, and you can easily discern how far you need to lean to reach the glass. You now 
know why people with one eye often have difficulty with distance perception. 
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Perspective alone is enough to create the appearance of three dimensions. Note the cube 
shown previously in Figure 1.2, Even without coloring or shading, the cube still has the 
appearance of a three-dimensional object. Stare at the cube for long enough, however, and 
the front and back of the cube switch places. Your brain is confused by the lack of any 
surface coloration in the drawing. Figure 1.4 shows the output from the sample program 
BLOCK from this chapter’s subdirectory on the CD-ROM. Run this program as we progress 
toward a more and more realistic appearing cube. We see here that the cube resting on a 
plane has an exaggerated perspective but still can produce the “popping” effect when you 
stare at it. By pressing the spacebar, you will progress toward a more and more believable 
image. 


FIGURE 1.4 A line-drawn three-dimensional cube. 


3D Artifacts 

The reason the world doesn’t become suddenly flat when you cover one eye is that many 
of a 3D world’s effects are still present when viewed two-dimensionally. The effects are just 
enough to trigger your brain’s ability to discern depth. The most obvious cue is that 
nearby objects appear larger than distant objects. This perspective effect is called 
foreshortening. This effect and color changes, textures, lighting, shading, and variations of 
color intensities (due to lighting) together add up to our perception of a three-dimensional 
image. In the next section, we take a survey of these tricks. 


A Survey of 3D Effects 


Now you have some idea that the illusion of 3D is created on a flat computer screen by 
means of a bag full of perspective and artistic tricks. Let’s review some of these effects so 
we can refer to them later in the book, and you'll know what we are talking about. 


The first term you should know is render. Rendering is the act of taking a geometric 
description of a three-dimensional object and turning it into an image of that object 
onscreen. All the following 3D effects are applied when rendering the objects or scene. 
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Perspective 

Perspective refers to the angles between lines that lend the illusion of three dimensions. 
Figure 1.4 shows a three-dimensional cube drawn with lines. This is a powerful illusion, 
but it can still cause perception problems as we mentioned earlier. (Just stare at this cube 
for a while, and it starts popping in and out.) In Figure 1.5, on the other hand, the brain is 
given more clues as to the true orientation of the cube because of hidden line removal. 
You expect the front of an object to obscure the back of the object from view. For solid 
surfaces, we call this hidden surface removal. 


FIGURE 1.5 Amore convincing solid cube. 


Color and Shading 

If we stare at the cube in Figure 1.5 long enough, we can convince ourselves that we are 
looking at a recessed image, and not the outward surfaces of a cube. To further our percep- 
tion, we must move beyond line drawing and add color to create solid objects. Figure 1.6 
shows what happens when we naively add red to the color of the cube. It doesn’t look like 
a cube anymore. By applying different colors to each side, as shown in Figure 1.7, we 
regain our perception of a solid object. 


FIGURE 1.6 Adding color alone can create further confusion. 


A Survey of 3D Effects 


FIGURE 1.7 Adding different colors increases the illusion of three dimensions. 


Light and Shadows 

Making each side of the cube a different color helps your eye pick out the different sides of 
the object. By shading each side appropriately, we can give the cube the appearance of 
being one solid color (or material) but also show it is illuminated by a light at an angle, as 
shown in Figure 1.8. Figure 1.9 goes a step further by adding a shadow behind the cube. 
Now we are simulating the effects of light on one or more objects and their interactions. 
Our illusion at this point is very convincing. 


FIGURE 1.8 Proper shading creates the illusion of illumination. 
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FIGURE 1.9 Adding a shadow to further increase realism. 


Texture Mapping 


Achieving a high level of realism with nothing but thousands or millions of tiny lit and 
shaded polygons is a matter of brute force and a lot of hard work. Unfortunately, the more 
geometry you throw at graphics hardware, the longer it takes to render. A clever technique 
allows you to use simpler geometry but achieve a higher degree of realism. This technique 
takes an image, such as a photograph of a real surface or detail, and then applies that 
image to the surface of a polygon. 


Instead of plain-colored materials, you can have wood grains, cloth, bricks, and so on. 
This technique of applying an image to a polygon to supply additional detail is called 
texture mapping. The image you supply is called a texture, and the individual elements of 
the texture are called texels. Finally, the process of stretching or compressing the texels 
over the surface of an object is called filtering. Figure 1.10 shows the now familiar cube 
example with textures applied to each polygon. 


FIGURE 1.10 Texture mapping adds detail without adding additional geometry. 
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Fog 

Most of us know what fog is. Fog is an atmospheric effect that adds haziness to objects in 
a scene, which is usually a relation of how far away the objects in the scene are from the 
viewer and how thick the fog is. Objects very far away (or nearby if the fog is thick) might 
even be totally obscured. 


Figure 1.11 shows the skyfly GLUT demo (included with the GLUT distribution on the 
CD-ROM) with fog enabled. Note how the fog lends substantially to the believability of 
the terrain. 


FIGURE 1.11 Fog effects provide a convincing illusion for wide open spaces. 


Blending and Transparency 

Blending is the combination of colors or objects on the screen. This is similar to the effect 
you get with double-exposure photography, where two images are superimposed. You can 
use the blending effect for a variety of purposes. By varying the amount each object is 
blended with the scene, you can make objects look transparent such that you see the 
object and what is behind it (such as glass or a ghost image). 


You can also use blending to achieve an illusion of reflection, as shown in Figure 1.12. You 
see a textured cube rendered twice. First, the cube is rendered upside down below the floor 
level. The marble floor is then blended with the scene, allowing the cube to show through. 
Finally, the cube is drawn again right side up and floating over the floor. The result is the 
appearance of a reflection in a shiny marble surface. 
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FIGURE 1.12 Blending used to achieve a reflection effect. 


Antialiasing 

Aliasing is an effect that is visible onscreen due to the fact that an image consists of 
discrete pixels. In Figure 1.13, you can see that the lines that make up the cube have 
jagged edges (sometimes called jaggies). By carefully blending the lines with the back- 
ground color, you can eliminate the jagged edges and give the lines a smooth appearance, 
as shown in Figure 1.14. This blending technique is called antialiasing. You can also apply 
antialiasing to polygon edges, making an object or scene look more realistic. This Holy 
Grail of real-time graphics is often referred to as photo-realistic rendering. 


FIGURE 1.13 Cube with jagged lines drawn. 


Common Uses for 3D Graphics 


FIGURE 1.14 Cube with smoother antialiased lines. 


Common Uses for 3D Graphics 


Three-dimensional graphics have many uses in modern computer applications. 
Applications for real-time 3D graphics range from interactive games and simulations to 
data visualization for scientific, medical, or business uses. Higher-end 3D graphics find 
their way into movies and technical and educational publications as well. 


Real-Time 3D 

As defined earlier, real-time 3D graphics are animated and interactive with the user. One 
of the earliest uses for real-time 3D graphics was in military flight simulators. Even today, 
flight simulators are a popular diversion for the home enthusiast. Figure 1.15 shows a 
screenshot from a popular flight simulator that uses OpenGL for 3D rendering 

(ww. flightgear.org). 


FIGURE 1.15 A popular OpenGL-based flight simulator from Flight Gear. 
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The applications for 3D graphics on the PC are almost limitless. Perhaps the most 
common use today is for computer gaming. Hardly a title ships today that does not 
require a 3D graphics card in your PC to play. 3D has always been popular for scientific 
visualization and engineering applications, but the explosion of cheap 3D hardware has 
empowered these applications like never before. Business applications are also taking 
advantage of the new availability of hardware to incorporate more and more complex 
business graphics and database mining visualization techniques. Even the modern GUI is 
being effected, and is beginning to evolve to take advantage of 3D hardware capabilities. 
The new Macintosh OS X, for example, uses OpenGL to render all its windows and 
controls for a powerful and eye-popping visual interface. 


Figures 1.16 through 1.20 show some of the myriad applications of real-time 3D graphics 
on the modern PC. All these images were rendered using OpenGL. 


FIGURE 1.16 3D graphics used for computer-aided design (CAD). 
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FIGURE 1.17 3D graphics used for architectural or civil planning (image courtesy of Real 3D, 
Inc.). 


Common Uses for 3D Graphics 
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FIGURE 1.19 3D graphics used for scientific visualization. 


Non-Real-Time 3D 


Some compromise is required for real-time 3D applications. Given more processing time, 
you can generate higher quality 3D graphics. Typically, you design models and scenes, and 
a ray tracer processes the definition to produce a high-quality 3D image. The typical 
process is that some modeling application uses real-time 3D graphics to interact with the 
artist to create the content. Then the frames are sent to another application (the ray 
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tracer), which renders the image. Rendering a single frame for a movie such as Toy Story 
could take hours on a very fast computer, for example. The process of rendering and 
saving many thousands of frames generates an animated sequence for playback. Although 
the playback might appear real-time, the content is not interactive, so it is not considered 
real-time, but rather pre-rendered. 


FIGURE 1.20 3D graphics used for entertainment (Descent 3 from Outrage Entertainment, 
Inc.). 


Figure 1.21 shows an example from the CD-ROM. This spinning image shows crystal 
letters that spell OpenGL. The letters are transparent and fully antialiased and show a 
myriad of reflections and shadow effects. The file to play this animation on your computer 
is opengl.avi in the root directory of the CD-ROM that accompanies this book. This large 
file (more than 35MB!) took hours to render. 


FIGURE 1.21 High-quality pre-rendered animation. 


Basic 3D Programming Principles 


Now, you have a pretty good idea of the basics of real-time 3D. We’ve covered some termi- 
nology and some sample applications on the PC. How do you actually create these images 
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on your PC? Well, that’s what the rest of this book is about! You still need a little more 
introduction to the basics, which we present here. 


Immediate Mode and Retained Mode (Scene Graphs) 

There are two different approaches to programming APIs for real-time 3D graphics. The 
first approach is called retained mode. In retained mode, you provide the API or toolkit 
with a description of your objects and the scene. The graphics package then creates the 
image onscreen. The only additional manipulation you might make is to give commands 
to change the location and viewing orientation of the user (also called the camera) or 
other objects in the scene. 


This type of approach is typical of ray tracers and many commercial flight simulators and 
image generators. Programmatically, the structure that is built is called a scene graph. The 
scene graph is a data structure (usually a DAG, or directed acyclic graph, for you computer 
science majors) that contains all the objects in your scene and their relationships to one 
another. Many high-level toolkits or “game engines” use this approach. The programmer 
doesn’t need to understand the finer points of rendering, only that he has a model or 
database that will be handed over to the graphics library, which takes care of the 
rendering. 


The second approach to 3D rendering is called immediate mode. Most retained mode APIs 
or scene graphs use an immediate mode API internally to actually perform the rendering. 
In immediate mode, you don’t describe your models and environment from as high a 
level. Instead, you issue commands directly to the graphics processor that has an immedi- 
ate effect on its state and the state of all subsequent commands. 


With immediate mode, new commands have no effect on rendering commands that have 
already been executed. This gives you a great deal of low-level control. For example, you 
can render a series of textured unlit polygons to represent the sky. Then you issue a 
command to turn off texturing, followed by a command to turn on lighting. Thereafter, 
all geometry (probably drawn on the ground) that you render is affected by the light but is 
not textured with the sky image. 


Coordinate Systems 

Let’s consider now how we describe objects in three dimensions. Before you can specify an 
object’s location and size, you need a frame of reference to measure and locate against. 
When you draw lines or plot points on a simple flat computer screen, you specify a posi- 
tion in terms of a row and column. For example, a standard VGA screen has 640 pixels 
from the left to right and 480 pixels from top to bottom. To specify a point in the middle 
of the screen, you specify that a point should be plotted at (320,240)—that is, 320 pixels 
from the left of the screen and 240 pixels down from the top of the screen. 


In OpenGL, or almost any 3D API, when you create a window to draw in, you must also 
specify the coordinate system you want to use and how to map the specified coordinates 
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into physical screen pixels. Let's first see how this applies to two-dimensional drawing and 
then extend the principle to three dimensions. 


2D Cartesian Coordinates 

The most common coordinate system for two-dimensional plotting is the Cartesian coor- 
dinate system. Cartesian coordinates are specified by an x coordinate and a y coordinate. 
The x coordinate is a measure of position in the horizontal direction, and y is a measure 

of position in the vertical direction. 


The origin of the Cartesian system is at x=0, y=0. Cartesian coordinates are written as coor- 
dinate pairs in parentheses, with the x coordinate first and the y coordinate second, sepa- 
rated by a comma. For example, the origin is written as (0,0). Figure 1.22 depicts the 
Cartesian coordinate system in two dimensions. The x and y lines with tick marks are 
called the axes and can extend from negative to positive infinity. This figure represents the 
true Cartesian coordinate system pretty much as you used it in grade school. Today, differ- 
ing window mapping modes can cause the coordinates you specify when drawing to be 
interpreted differently. Later in the book, you’ll see how to map this true coordinate space 
to window coordinates in different ways. 


FIGURE 1.22 The Cartesian plane. 


The x-axis and y-axis are perpendicular (intersecting at a right angle) and together define 
the xy plane. A plane is, most simply put, a flat surface. In any coordinate system, two axes 
(or two lines) that intersect at right angles define a plane. In a system with only two axes, 
there is naturally only one plane to draw on. 
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Coordinate Clipping 

A window is measured physically in terms of pixels. Before you can start plotting points, 
lines, and shapes in a window, you must tell OpenGL how to translate specified coordi- 
nate pairs into screen coordinates. You do this by specifying the region of Cartesian space 
that occupies the window; this region is known as the clipping region. In two-dimensional 
space, the clipping region is the minimum and maximum x and y values that are inside 
the window. Another way of looking at this is specifying the origin’s location in relation 
to the window. Figure 1.23 shows two common clipping regions. 


+X 


FIGURE 1.23 Two clipping regions. 


In the first example, on the left of Figure 1.23, x coordinates in the window range left to 
right from 0 to +150, and the y coordinates range bottom to top from 0 to +100. A point 
in the middle of the screen would be represented as (75,50). The second example shows a 
clipping area with x coordinates ranging left to right from —75 to +75 and y coordinates 
ranging bottom to top from -50 to +50. In this example, a point in the middle of the 
screen would be at the origin (0,0). It is also possible using OpenGL functions (or ordinary 
Windows functions for GDI drawing) to turn the coordinate system upside down or flip it 
right to left. In fact, the default mapping for Windows windows is for positive y to move 
down from the top to bottom of the window. Although useful when drawing text from 
top to bottom, this default mapping is not as convenient for drawing graphics. 


Viewports: Mapping Drawing Coordinates to Window Coordinates 

Rarely will your clipping area width and height exactly match the width and height of the 
window in pixels. The coordinate system must therefore be mapped from logical Cartesian 
coordinates to physical screen pixel coordinates. This mapping is specified by a setting 
known as the viewport. The viewport is the region within the window’s client area that is 
used for drawing the clipping area. The viewport simply maps the clipping area to a region 
of the window. Usually, the viewport is defined as the entire window, but this is not 
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strictly necessary; for instance, you might want to draw only in the lower half of the 
window. 


Figure 1.24 shows a large window measuring 300x200 pixels with the viewport defined as 
the entire client area. If the clipping area for this window were set to 0 to 150 along the x- 
axis and 0 to 100 along the y-axis, the logical coordinates would be mapped to a larger 
screen coordinate system in the viewing window. Each increment in the logical coordinate 
system would be matched by two increments in the physical coordinate system (pixels) of 
the window. 


(150,100) 


bar, 


FIGURE 1.24 A viewport defined as twice the size of the clipping area. 


In contrast, Figure 1.25 shows a viewport that matches the clipping area. The viewing 
window is still 300x200 pixels, however, and this causes the viewing area to occupy the 
lower-left side of the window. 


(150,100) 
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FIGURE 1.25 A viewport defined as the same dimensions as the clipping area. 
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You can use viewports to shrink or enlarge the image inside the window and to display 
only a portion of the clipping area by setting the viewport to be larger than the window’s 
client area. _ 


The Vertex-A Position in Space 

In both 2D and 3D, when you draw an object, you actually compose it with several 
smaller shapes called primitives. Primitives are one- or two-dimensional entities or surfaces 
such as points, lines, and polygons (a flat, multisided shape) that are assembled in 3D 
space to create 3D objects. For example, a three-dimensional cube consists of six two- 
dimensional squares, each placed on a separate face. Each corner of the square (or of any 
primitive) is called a vertex. These vertices are then specified to occupy a particular coordi- 
nate in 3D space. A vertex is nothing more than a coordinate in 2D or 3D space. Creating 
solid 3D geometry is little more than a game of connect-the-dots! You’ll learn about all the 
OpenGL primitives and how to use them in Chapter 3, “Drawing in Space: Geometric 
Primitives.” 


3D Cartesian Coordinates 

Now, we extend our two-dimensional coordinate system into the third dimension and add 
a depth component. Figure 1.26 shows the Cartesian coordinate system with a new axis, z. 
The z-axis is perpendicular to both the x- and y-axes. It represents a line drawn perpendic- 
ularly from the center of the screen heading toward the viewer. (We have rotated our view 
of the coordinate system from Figure 1.22 to the left with respect to the y-axis and down 
and back with respect to the x-axis. If we hadn’t, the z-axis would come straight out at 
you, and you wouldn't see it.) Now, we specify a position in three-dimensional space with 
three coordinates: x, y, and z. Figure 1.26 shows the point (-4,4,4) for clarification. 


+y 
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FIGURE 1.26 Cartesian coordinates in three dimensions. 
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Projections: Getting 3D to 2D 

You’ve seen how to specify a position in 3D space using Cartesian coordinates. No matter 
how we might convince your eye, however, pixels on a screen have only two dimensions. 
How does OpenGL translate these Cartesian coordinates into two-dimensional coordinates 
that can be plotted on a screen? The short answer is “Trigonometry and simple matrix 
manipulation.” Simple? Well, not really; we could actually go on for many pages and lose 
most of our readers who didn’t take or don’t remember their linear algebra from college 
explaining this “simple” technique. You’ll learn more about it in Chapter 4, “Geometric 
Transformations: The Pipeline,” and for a deeper discussion, you can check out the refer- 
ences in Appendix A, “Further Reading.” Fortunately, you don’t need a deep understand- 
ing of the math to use OpenGL to create graphics. You might, however, discover that the 
deeper your understanding goes, the more powerful a tool OpenGL becomes! 


The first concept you really need to understand is called projection. The 3D coordinates you 
use to create geometry are flattened or projected onto a 2D surface (the window back- 
ground). It’s like tracing the outlines of some object behind a piece of glass with a black 
marker. When the object is gone or you move the glass, you can still see the outline of the 
object with its angular edges. In Figure 1.27, a house in the background is traced onto a 
flat piece of glass. By specifying the projection, you specify the viewing volume that you 
want displayed in your window and how it should be transformed. 


FIGURE 1.27 A 3D image projected onto a 2D surface. 


Orthographic Projections 

You are mostly concerned with two main types of projections in OpenGL. The first is 
called an orthographic or parallel projection. You use this projection by specifying a square 
or rectangular viewing volume. Anything outside this volume is not drawn. Furthermore, 
all objects that have the same dimensions appear the same size, regardless of whether they 
are far away or nearby. This type of projection (shown in Figure 1.28) is most often used in 
architectural design, computer-aided design (CAD), or 2D graphs. Frequently, you will use 
an orthographic projection to add text or 2D overlays on top of your 3D graphic scene. 
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Far 


Left Right 


Bottom 
FIGURE 1.28 The clipping volume for an orthographic projection. 


You specify the viewing volume in an orthographic projection by specifying the far, near, 
left, right, top, and bottom clipping planes. Objects and figures that you place within this 
viewing volume are then projected (taking into account their orientation) to a 2D image 
that appears on your screen. 


Perspective Projections 

The second and more common projection is the perspective projection. This projection adds 
the effect that distant objects appear smaller than nearby objects. The viewing volume (see 
Figure 1.29) is something like a pyramid with the top shaved off. The remaining shape is 
called the frustum. Objects nearer to the front of the viewing volume appear close to their 
original size, but objects near the back of the volume shrink as they are projected to the 
front of the volume. This type of projection gives the most realism for simulation and 3D 
animation. 
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FIGURE 1.29 The clipping volume (frustum) for a perspective projection. 


Summary 


In this chapter, we introduced the basics of 3D graphics. You saw why you actually need 
two images of an object from different angles to be able to perceive true three-dimensional 
space. You also saw the illusion of depth created in a 2D drawing by means of perspective, 
hidden line removal, coloring, shading, and other techniques. The Cartesian coordinate 
system was introduced for 2D and 3D drawing, and you learned about two methods used 
by OpenGL to project three-dimensional drawings onto a two-dimensional screen. 


We purposely left out the details of how these effects are actually created by OpenGL. In 
the chapters that follow, you will find out how to employ these techniques and take 
maximum advantage of OpenGL’s power. On the companion CD, you'll find one program 
for this chapter that demonstrates the 3D effects covered here. In the program BLOCK, 
pressing the spacebar advances you from a wireframe cube to a fully lit and textured block 
complete with shadow. You won’t understand the code at this point, but it makes a power- 
ful demonstration of what is to come. By the time you finish this book, you will be able to 
revisit this example and even be able to write it from scratch yourself. 


CHAPTER 2 


Using OpenGL 


by Richard S. Wright, Jr. 


WHAT YOU'LL LEARN IN THIS CHAPTER: 


¢ Where OpenGL came from and where it’s going 

¢ Which headers need to be included in your project 

¢ How to use GLUT with OpenGL to create a window and draw in it 
¢ How to set colors using RGB (red, green, blue) components 

¢ How viewports and viewing volumes affect image dimensions 

¢ How to perform a simple animation using double buffering 

¢ How the OpenGL state machine works 

¢ How to check for OpenGL errors 


¢ How to make use of OpenGL extensions 


What Is OpenGL? 


OpenGL is strictly defined as “a software interface to graphics hardware.” In essence, it is a 
3D graphics and modeling library that is highly portable and very fast. Using OpenGL, 
you can create elegant and beautiful 3D graphics with nearly the visual quality of a ray 
tracer. The greatest advantage to using OpenGL is that it is orders of magnitude faster than 
a ray tracer. Initially, it used algorithms carefully developed and optimized by Silicon 
Graphics, Inc. (SGI), an acknowledged world leader in computer graphics and animation. 
Over time OpenGL has evolved as other vendors have contributed their expertise and 
intellectual property to develop high-performance implementations of their own. 


OpenGL is not a programming language like C or C++. It is more like the C runtime 
library, which provides some prepackaged functionality. There really is no such thing as an 
“OpenGL program,” but rather a program the developer wrote that “happens” to use 
OpenGL as one of its Application Programming Interfaces (APIs). You might use the 
Windows API to access a file or the Internet, and you might use OpenGL to create real- 
time 3D graphics. 
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OpenGL is intended for use with computer hardware that is designed and optimized for 
the display and manipulation of 3D graphics. Software-only, “generic” implementations of 
OpenGL are also possible, and the Microsoft implementations fall into this category. With 
a software-only implementation, rendering may not be performed as quickly, and some 
advanced special effects may not be available. However, using a software implementation 
means that your program can potentially run on a wider variety of computer systems that 
may not have a 3D graphics card installed. 


OpenGL is used for a variety of purposes, from CAD engineering and architectural applica- 
tions to modeling programs used to create computer-generated monsters in blockbuster 
movies. The introduction of an industry-standard 3D API to mass-market operating 
systems such as Microsoft Windows and the Macintosh OS X has some exciting repercus- 
sions. With hardware acceleration and fast PC microprocessors becoming commonplace, 
3D graphics are now typical components of consumer and business applications, not only 
of games and scientific applications. 


Evolution of a Standard 


The forerunner of OpenGL was IRIS GL from Silicon Graphics. Originally a 2D graphics 
library, it evolved into the 3D programming API for that company’s high-end IRIS graphics 
workstations. These computers were more than just general-purpose computers; they had 
specialized hardware optimized for the display of sophisticated graphics. The hardware 
provided ultra-fast matrix transformations (a prerequisite for 3D graphics), hardware 
support for depth buffering, and other features. 


Sometimes, however, the evolution of technology is hampered by the need to support 
legacy systems. IRIS GL had not been designed from the onset to have a vertex-style geom- 
etry processing interface, and it became apparent that to move forward SGI needed to 
make a clean break. 


OpenGL is the result of SGI’s efforts to evolve and improve IRIS GL’s portability. The new 
graphics API would offer the power of GL but would be an “open” standard, with input 
from other graphics hardware vendors, and would allow for easier adaptability to other 
hardware platforms and operating systems. OpenGL would be designed from the ground 
up for 3D geometry processing. 


The OpenGL ARB 

An open standard is not really open if only one vendor controls it. SGI’s business at the 
time was high-end computer graphics. Once you're at the top, you find that the opportu- 
nities for growth are somewhat limited. SGI realized that it would also be good for the 
company to do something good for the industry to help grow the market for high-end 
computer graphics hardware. A truly open standard embraced by a number of vendors 
would make it easier for programmers to create applications and content that is available 
for a wider variety of platforms. Software is what sells computers, and if SGI wanted to sell 
more computers, it needed more software that would run on its computers. Other vendors 
realized this, too, and the OpenGL Architecture Review Board (ARB) was born. 


What Is OpenGL? 


Although SGI controlled licensing of the OpenGL API, the founding members of the 
OpenGL ARB were SGI, Digital Equipment Corporation, IBM, Intel, and Microsoft. On July 
1, 1992, Version 1.0 of the OpenGL specification was introduced. More recently, the ARB 
consists of many more members, many from the PC hardware community, and it meets 
four times a year to maintain and enhance the specification and to make plans to promote 
the OpenGL standard. 


These meetings are open to the public, and nonmember companies can participate in 
discussions and even vote in straw polls. Permission to attend must be requested in 
advance, and meetings are kept small to improve productivity. Nonmember companies 
actually contribute significantly to the specification and do meaningful work on the 
conformance tests and other subcommittees. 


Licensing and Conformance 

An implementation of OpenGL is either a software library that creates three-dimensional 
images in response to the OpenGL function calls or a driver for a hardware device (usually 
a display card) that does the same. Hardware implementations are many times faster than 
software implementations and are now common even on inexpensive PCs. 


A vendor who wants to create and market an OpenGL implementation must first license 
OpenGL from SGI. SGI provides the licensee with a sample implementation (entirely in 
software) and a device driver kit if the licensee is a PC hardware vendor. The vendor then 
uses this to create its own optimized implementation and can add value with its own 
extensions. Competition among vendors typically is based on performance, image quality, 
and driver stability. 


In addition, the vendor’s implementation must pass the OpenGL conformance tests. These 
tests are designed to ensure that an implementation is complete (it contains all the neces- 
sary function calls) and produces 3D rendered output that is reasonably acceptable for a 
given set of functions. 


Software developers do not need to license OpenGL or pay any fees to make use of 
OpenGL drivers. OpenGL is natively supported by the operating system, and licensed 
drivers are provided by the hardware vendors themselves. A free open source software 
implementation of OpenGL called MESA is included on the CD with this book. For legal 
reasons, MESA is not an “official” implementation of OpenGL, but the API is identical and 
we all know it is just OpenGL! Many Linux open source OpenGL hardware drivers are in 
fact based on the MESA source code. 


The API Wars 


Standards are good for everyone, except for vendors who think that they should be the 
only vendors customers can choose from because they know best what customers need. 
We have a special legal word for vendors who manage to achieve this status: monopoly. 
Most companies recognize that competition is good for everyone in the long run and will 
endorse, support, and even contribute to industry standards. An interesting diversion from 
this ideal occurred during OpenGL’s youth on the Windows platform. 
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Enter DirectX 

Few remember anymore what a “Windows Accelerator” is, but there was a time when you 
could buy a special graphics card that accelerated the 2D graphics commands used by 
Microsoft Windows. Although Graphics Device Interface (GDI) accelerated graphics cards 
were great for users of word processors or desktop publishing applications, they fell far 
short of adequate for PC game programmers. Early Windows-based games consisted 
primarily of puzzle or card games that did not need speedy animation. PC games that 
required fast animation, such as action video games, remained DOS-based programs that 
could control the entire screen and did not have to share system resources with other 
programs that might be running at the same time. 


Microsoft made some attempts to win game programmers over to developing Windows 
native games, but early attempts to provide faster display access, such as the WinG API, 
still fell far short of the mark, and game programmers continued writing DOS programs 
that gave them direct access to graphics hardware. When Microsoft began shipping 
Windows 95, its first quasi-true 32-bit operating system for the consumer market, the 
company intended to put an end to DOS once and for all. The original Windows 95 Game 
Developers Kit included some new APIs for Windows aimed at game programmers. The 
most important of these was DirectDraw. 


To remain competitive, graphics card vendors now needed a GDI driver and a DirectDraw 
driver, but the driver framework was meant to provide the same low-level (and fast) access 
to graphics hardware under Windows that developers were used to getting with DOS. This 
time, Microsoft was more successful, and Windows 95 native game titles that took advan- 
tage of the new “game” APIs began shipping. This group of APIs later came to be known 
as DirectX. DirectX now contains a whole family of APIs meant to empower multimedia 
developers on the Windows platform. It would be fair to compare DirectX on Windows to 
QuickTime on the Mac: Both offer a variety of multimedia services and APIs to the 
programmer. 


The original intent for DirectX was direct low-level access to hardware features. This origi- 
nal purpose has been diluted over time as DirectX has come to include higher-level soft- 
ware functionality and additional layers over the low-level devices. What was originally 
the Windows Game Developers Kit has evolved over time to become the “DirectX Media 
APIs.” Many of the DirectX APIs are independent of one another, and you can mix and 
match them at will. For example, you can use a third-party sound library with a Direct3D- 
rendered game or even use DirectSound with an OpenGL-rendered game. 


OpenGL Comes to the PC 

Around the same time that one group at Microsoft was focusing on establishing Windows 
as a viable gaming platform, OpenGL (which was a younger API at the time) began to gain 
some momentum on the PC as well and was being promoted by yet another group at 
Microsoft as the API of choice for scientific and engineering applications. Microsoft was 
even one of the founding members of the OpenGL ARB. Supporting OpenGL on the 
Windows platform would enable Microsoft to compete with UNIX-based workstations that 
had traditionally been the host of advanced visualization and simulation applications. 


What Is OpenGL? 


Originally, 3D graphics hardware for the PC was very expensive, so it was not frequently 
used for computer games. Only industries with deep pockets could afford such hardware, 
and as a result OpenGL first became popular in the fields of CAD, simulation, and scien- 
tific visualization. In these fields, performance was often a premium, so OpenGL was 
designed and evolved with performance as an important goal of the API. As 3D games 
became popular on the PC, OpenGL was applied to this domain as well and in some cases 
with great success. 


By the time 3D graphics hardware for the PC became inexpensive enough to attract PC 
gamers, OpenGL was a mature and well-established 3D rendering API with a strong feature 
set. This timing coincided with Microsoft’s attempts to promote its new Direct3D as a 3D 
rendering API for games. Ordinarily, a new, difficult-to-use, and relatively feature-weak API 
such as Direct3D would not have survived in the marketplace. 


Many veteran 3D game programmers apply the unofficial term API Wars to this period of 
time when Microsoft and SGI were battling for the mind share of 3D game developers. 
Microsoft was a founding member of the OpenGL ARB and wanted OpenGL on Windows 
so that UNIX workstation software vendors could more easily port their scientific and 
engineering applications to Windows NT. Portability, however, was a two-edged sword; it 
also meant that developers who target Windows could later port their applications to 
other operating systems. PCs were well entrenched in the business workplace. Now it was 
time to go after the consumer market in a much bigger way. 


OpenGL for Games? 

When John Carmack, the author of one of the most popular 3D games of all time, rewrote 
his popular game Quake to use OpenGL over one weekend, his efforts set the gaming 
world abuzz. John demonstrated easily how 10 or so lines of OpenGL code required two to 
three pages of Direct3D code to accomplish the same task (rendering a few triangles). 
Many game programmers began to look carefully at OpenGL as a 3D rendering API suit- 
able for games and not just “scientific” applications. John Carmack’s company, ID 
Software, also had a policy of providing its games on several different platforms and oper- 
ating systems. OpenGL simply made doing so much easier. 


By this point, Microsoft had too much invested in its Direct3D API to back down from its 
own brainchild. The company was caught between a rock and a hard place. It could not 
back off promoting Direct3D for games because that would mean giving up the needed 
influence to keep game developers developing for Windows exclusively. Consumers like to 
play games, and keeping a hold on the consumer OS market meant keeping a hold on the 
number-one consumer application category. Likewise, Microsoft could not back off 
supporting OpenGL for the workstation market because that would mean giving up the 
needed influence to attract developers and applications away from competing operating 
systems. 


Microsoft began to insist that OpenGL was for precise and exacting rendering needs and 
Direct3D was for real-time rendering. Official Microsoft literature described OpenGL as 
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being something more like a ray tracer than the real-time rendering API it was designed to 
be. Why Microsoft wasn’t thrown off the ARB for such a misinformation campaign 
remains under lock and key and a few dozen nondisclosure agreements. SGI took up the 
task of promoting OpenGL as an alternative to Direct3D, and most developers wanted to 
be able to choose which technology to use for their games. 


Direct3D’s Head Start 

Before 3D hardware was firmly entrenched, game developers had to use software rendering 
to create 3D games. It turned out that Microsoft’s Direct3D software renderer was many 
times faster than its own OpenGL renderer. The reason for this difference, according to 
Microsoft, was that OpenGL is meant for CAD; unfortunately, game programmers don’t 
know much about CAD, but CAD users don’t usually like waiting all afternoon for their 
drawings to rotate either. Microsoft had assumed that OpenGL would be used only with 
expensive 3D graphics cards in the CAD industry and had not devoted the resources to 
creating a fast software implementation. Without hardware acceleration, OpenGL was 
really useless on Windows for anything other than simple static 3D graphics and visualiza- 
tions. This had nothing to do with the difference between the OpenGL and Direct3D APIs, 
but only in how they had been implemented by Microsoft. 


Silicon Graphics took up the challenge of demonstrating that the design of the OpenGL 
API was not the flaw, but rather the implementation. At the 1996 SigGraph conference in 
New Orleans, SGI demonstrated its own OpenGL implementation for Windows. By 
porting several Direct3D demos to OpenGL, the company easily showed OpenGL running 
the same animations at equivalent and better speeds. 


In reality, however, both software implementations were too slow for really good games. 
Game developers could write their own optimized 3D code, take liberal shortcuts that 
would not impact their game, and get much better performance. What really launched 
both OpenGL and Direct3D as viable gaming APIs was the proliferation of cheap 3D accel- 
erated hardware for the PC. What happened next is history. 


Dirty Pool 

Some game developers began to develop OpenGL-enabled titles for the 1997 Christmas 
season. Microsoft encouraged 3D hardware vendors to develop Direct3D drivers, and if 
they wanted to do OpenGL for Windows 98, they should use a driver kit that Microsoft 
provided. This kit used the Mini-Client Driver (MCD), which enabled hardware vendors to 
easily create OpenGL hardware drivers for Windows 98. In response to SGI’s OpenGL 
implementation, an embarrassed Microsoft spent a lot of time tuning its own implementa- 
tion, and the MCD allowed vendors to tap into this code for everything but the actual 
drawing commands, which were handled by the graphics card. However, Microsoft was 
still insisting that OpenGL was not suitable for games development, and the MCD was 
meant to provide a ready route to the blossoming PC CAD market. Nearly all major PC 3D 
vendors had MCD-based drivers to demonstrate privately at the 1997 Computer Game 
Developers Conference. Most were quiet about this fact because it was known that hard- 
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ware vendors who strongly supported OpenGL for games had difficulty getting needed 
support for their Direct3D efforts. Because most games were being developed with Direct 
3D, this would be market suicide. 


In the summer of 1997, Microsoft announced that it would not be licensing the MCD 
code beyond the development stage and vendors would not be allowed to release their 
drivers for Windows 98. They could, however, ship MCD-based drivers for Windows NT, 
the workstation platform where OpenGL belonged. As a result, software vendors who 
devoted time to OpenGL versions of their games could not ship their titles with OpenGL 
support for Christmas, hardware vendors were left without shippable OpenGL drivers, and 
Direct3D conveniently got a year’s head start on OpenGL as a hardware API standard for 
games. Meanwhile, Microsoft restated that OpenGL was for non-real-time NT-based work- 
station applications and Direct 3D was for Windows 98 consumer games. 


Fortunately, this situation did not last too long. Silicon Graphics released its own OpenGL 
driver kit, based on its speedy software implementation for Windows. SGI's driver kit used 
a much more complex driver mechanism than the MCD, called the Installable Client 
Driver (ICD). Microsoft had discouraged consumer hardware vendors from starting with 
the ICD because the MCD would be so much easier for them to use (this was before 
Microsoft pulled the rug out from under them). SGI’s kit, however, had an easier-to-use 
interface that made developing drivers similar to using the simpler MCD model, and it 
even improved driver performance. 


As hardware drivers for OpenGL began to show up for Windows 98, game companies once 
again seriously began looking at using OpenGL for game development. Having won its 
head start, and now unable to further halt the advancement of OpenGL’s use for consumer 
applications, Microsoft relented and again agreed to support OpenGL for Windows 98. 
This time, however, SGI had to drop all marketing efforts aimed at evangelizing OpenGL 
toward game developers. Instead, the two companies would work together on a new joint 
API called Fahrenheit. Fahrenheit would incorporate the best of Direct3D and OpenGL for 
a new unified 3D API (available only on Windows and SGI hardware). At the time, SGI 
was losing the battle with NT for workstation sales, so it relented. Simultaneously, the 
company released a new SGI-branded NT workstation, with Microsoft’s full endorsement. 
OpenGL had lost its greatest supporter for the consumer PC platform. 


The Future of OpenGL 

Many in the industry saw the Fahrenheit agreement as the beginning of the end for 
OpenGL. But a funny thing happened on the way to oblivion, and without SGI, OpenGL 
began to take on a life of its own. When OpenGL was again widely available on consumer 
hardware, developers didn’t really need SGI or anyone else touting the virtues of OpenGL. 
OpenGL was easy to use and had been around for years. This meant there was an abun- 
dance of documentation (including the first edition of this book), sample programs, 
SigGraph papers, and so on. OpenGL began to flourish. 
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As more developers began to use OpenGL, it became clear who was really in charge of the 
industry: the developers. The more applications that shipped with OpenGL support, the 
more pressure mounted on hardware vendors to produce better OpenGL hardware and 
high-quality drivers. Consumers don’t really care about API technology. They just want 
software that works, and they will buy whatever graphics card runs their favorite game the 
best. Developers care about time to market, portability, and code reuse. (Go ahead. Try to 
recompile that old Direct3D 4.0 program. I dare you!) Using OpenGL enabled many devel- 
opers to meet customer demand better, and in the end it’s the customers who pay the 
bills. 


As time passed, Fahrenheit fell solely into Microsoft’s hands and was eventually discontin- 
ued altogether. One can only speculate whether that was Microsoft’s intent from the 
beginning. Direct3D has evolved further to include more and more OpenGL features, 
functionality, and ease of use. OpenGL’s popularity has continued to grow as an alterna- 
tive to Windows-specific rendering technology and is now widely supported across all 
major operating systems and hardware devices. Even cell phones with 3D graphics tech- 
nology support a subset of OpenGL, called OpenGL ES. Today, all new 3D accelerated 
graphics cards for the PC ship with both OpenGL and Direct3D drivers. This is largely due 
to the fact that many developers continue to prefer OpenGL for new development. 
OpenGL today is widely recognized and accepted as an industry standard API for real-time 
3D graphics. 


Developers have continued to be attracted to OpenGL, and despite any political pressures, 
hardware vendors must satisfy the developers who make software that runs on their hard- 
ware. Ultimately, consumer dollars determine what standard survives, and developers who 
use OpenGL are turning out better games and applications, on more platforms, and in less 
time than their competitors. Only a few years ago, game developers were creating games 
with Microsoft’s Direct 3D first because that was the only available API with a hardware 
driver model under consumer Windows—and then porting to OpenGL occasionally so 
that the same games ran under Windows NT (which didn’t support Direct3D). Today, 
many game and software companies are creating OpenGL versions first and then porting 
to other platforms such as the Macintosh. It turns out that competitive advantage is more 
profitable than political alliances. 


This momentum will carry OpenGL into the foreseeable future as the API of choice for a 
wide range of applications and hardware platforms. All this also makes OpenGL well posi- 
tioned to take advantage of future 3D graphics innovations. Because of OpenGL’s exten- 
sion mechanism, vendors can expose new hardware features without waiting on either the 
ARB or Microsoft, and cutting-edge developers can exploit them as soon as updated drivers 
are available. With the addition of the OpenGL shading language (see Part III of this 
book), OpenGL has shown its continuing adaptability to meet the challenge of an evolv- 
ing 3D graphics programming pipeline. Finally, OpenGL is a specification that has shown 
that it can be applied to a wide variety of programming paradigms. From C/C++ to Java 
and Visual Basic, even newer languages such as C# are now being used to create PC games 
using OpenGL. OpenGL is here to stay. 
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OpenGL is a procedural rather than a descriptive graphics API. Instead of describing the 

scene and how it should appear, the programmer actually prescribes the steps necessary to 

achieve a certain appearance or effect. These “steps” involve calls to the many OpenGL 

commands, These commands are used to draw graphics primitives such as points, lines, 

and polygons in three dimensions. In addition, OpenGL supports lighting and shading, N 
texture mapping, blending, transparency, animation, and many other special effects and 
capabilities. 


OpenGL does not include any functions for window management, user interaction, or file 
1/O. Each host environment (such as Microsoft Windows) has its own functions for this 
purpose and is responsible for implementing some means of handing over to OpenGL the 
drawing control of a window. 


There is no “OpenGL file format” for models or virtual environments. Programmers 
construct these environments to suit their own high-level needs and then carefully 
program them using the lower-level OpenGL commands. 


Generic Implementations 

As mentioned previously, a generic implementation is a software implementation. 
Hardware implementations are created for a specific hardware device, such as a graphics 
card or image generator. A generic implementation can technically run just about 
anywhere as long as the system can display the generated graphics image. 


Figure 2.1 shows the typical place that OpenGL and a generic implementation occupy 
when an application is running. The typical program calls many functions, some of which 
the programmer creates and some of which are provided by the operating system or the 
programming language’s runtime library. Windows applications wanting to create output 
onscreen usually call a Windows API called the Graphics Device Interface (GDI). The GDI 
contains methods that allow you to write text in a window, draw simple 2D lines, and 


so on. 
Application Program 


Rasterizer 


FIGURE 2.1 OpenGL's place in a typical application program. 
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Usually, graphics card vendors supply a hardware driver that GDI interfaces with to create 
output on your monitor. A software implementation of OpenGL takes graphics requests 
from an application and constructs (rasterizes) a color image of the 3D graphics. It then 
supplies this image to the GDI for display on the monitor. On other operating systems, 
the process is reasonably equivalent, but you replace the GDI with that operating system’s 
native display services. 


OpenGL has a couple of common generic implementations. Microsoft has shipped its soft- 
ware implementation with every version of Windows NT since version 3.5 and Windows 
95 (Service Release 2 and later). Windows 2000 and XP also contain support for OpenGL. 


SGI released a software implementation of OpenGL for Windows that greatly outper- 
formed Microsoft’s implementation. This implementation is not officially supported but is 
still occasionally used by developers. MESA 3D is another “unofficial” OpenGL software 
implementation that is widely supported in the open source community. Mesa 3D is not 
an OpenGL license, so it is an “OpenGL work-alike” rather than an official implementa- 
tion. In any respect other than legal, you can essentially consider it to be an OpenGL 
implementation nonetheless. The Mesa contributors even make a good attempt to pass the 
OpenGL conformance tests. 


Hardware Implementations 

A hardware implementation of OpenGL usually takes the form of a graphics card driver. 
Figure 2.2 shows its relationship to the application similarly to the way Figure 2.1 did for 
software implementations. Note that OpenGL API calls are passed to a hardware driver. 
This driver does not pass its output to the Windows GDI for display; the driver interfaces 
directly with the graphics display hardware. 


1/0 
Services 


0s 
Services 


FIGURE 2.2 Hardware-accelerated OpenGL’s place in a typical application program. 


A hardware implementation is often referred to as an accelerated implementation because 
hardware-assisted 3D graphics usually far outperform software-only implementations. 
What isn’t shown in Figure 2.2 is that sometimes part of the OpenGL functionality is still 
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implemented in software as part of the driver, and other features and functionality can be 
passed directly to the hardware. This idea brings us to our next topic: the OpenGL 
pipeline. 


The Pipeline 

The word pipeline is used to describe a process that can take two or more distinct stages or 
steps. Figure 2.3 shows a simplified version of the OpenGL pipeline. As an application 
makes OpenGL API function calls, the commands are placed in a command buffer. This 
buffer eventually fills with commands, vertex data, texture data, and so on. When the 
buffer is flushed, either programmatically or by the driver's design, the commands and 
data are passed to the next stage in the pipeline. 


OpenGL lilies 
API Calls 


FIGURE 2.3 A simplified version of the OpenGL pipeline. 


Vertex data is usually transformed and lit initially. In subsequent chapters, you'll find out 
more about what this means. For now, you can consider “Transform and Lighting” to be a 
mathematically intensive stage where points used to describe an object’s geometry are 
recalculated for the given object’s location and orientation. Lighting calculations are 
performed as well to indicate how brightly the colors should be at each vertex. 


When this stage is complete, the data is fed to the rasterization portion of the pipeline. 
The rasterizer actually creates the color image from the geometric, color, and texture data. 
The image is then placed in the frame buffer. The frame buffer is the memory of the graph- 
ics display device, which means the image is displayed on your screen. 


This diagram provides a simplistic view of the OpenGL pipeline, but it is sufficient for 
your current understanding of 3D graphics rendering. At a high level, this view is accurate, 
so we aren’t compromising your understanding, but at a low level, many more boxes 
appear inside each box shown here. There are also some exceptions, such as the arrow in 
the figure indicating that some commands skip the Transform and Lighting (T&L) stage 
altogether (such as displaying raw image data on the screen). 


Early OpenGL hardware accelerators were nothing more than fast rasterizers. They acceler- 
ated only the rasterization portion of the pipeline. The host system’s CPU did transform 
and lighting in a software implementation of that portion of the pipeline. Higher-end 
(more expensive) accelerators had T&L on the graphics accelerator. This arrangement put 
more of the OpenGL pipeline in hardware and thus provided for higher performance. 


Even most low-end consumer hardware today has the T&L stage in hardware. The net 
effect of this arrangement is that higher detailed models and more complex graphics are 
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possible at real-time rendering rates on inexpensive consumer hardware. Games and appli- 
cations developers can capitalize on this effect, yielding far more detailed and visually rich 
environments. 


OpenGL: An API, Not a Language 


For the most part, OpenGL is not a programming language; it is an Application 
Programming Interface (API). Whenever we say that a program is OpenGL-based or an 
OpenGL application, we mean that it was written in some programming language (such as 
C or C++) that makes calls to one or more of the OpenGL libraries. We are not saying that 
the program uses OpenGL exclusively to do drawing. It might combine the best features of 
two different graphics packages. Or it might use OpenGL for only a few specific tasks and 
environment-specific graphics (such as the Windows GDI) for others. The only exception 
to this rule of thumb is, of course, the OpenGL Shading Language, which will be covered 
later in this book. 


As an API, the OpenGL library follows the C calling convention, and in this book, the 
sample programs are written in C. C++ programs can easily access C functions and APIs in 
the same manner as C, with only some minor considerations. Most C++ programmers can 
still program in C, and we don’t want to exclude anyone or place any additional burden 
on the reader (such as having to get used to C++ syntax). Other programming languages— 
such as Visual Basic—that can call functions in C libraries can also make use of OpenGL, 
and OpenGL bindings are available for many other programming languages. Using 
OpenGL from these other languages is, however, outside the scope of this book and can be 
troublesome. To keep things simple and easily portable, we’ll stick with C for our exam- 
ples. 


Libraries and Headers 


Although OpenGL is a “standard” programming library, this library has many implemen- 
tations. Microsoft Windows ships with support for OpenGL as a software renderer. This 
means that when a program written to use OpenGL makes OpenGL function calls, the 
Microsoft implementation performs the 3D rendering functions, and you see the results in 
your application window. The actual Microsoft software implementation is in the 
openg132.d11 dynamic link library, located in the Windows system directory. On most 
platforms, the OpenGL library is accompanied by the OpenGL utility library (GLU), which 
on Windows is in glu32.d11, also located in the system directory. The utility library is a 
set of utility functions that perform common (but sometimes complex) tasks, such as 
special matrix calculations, or provide support for common types of curves and surfaces. 


The steps for setting up your compiler tools to link to the correct OpenGL libraries vary 
from tool to tool and from platform to platform. You can find some step-by-step instruc- 
tions for Windows, Macintosh, and Linux in the platform-specific chapters in Part II of 
this book. 


API Specifics 


Prototypes for all OpenGL functions, types, and macros are contained (by convention) in 
the header file g1.h. Microsoft programming tools ship with this file, and so do most 
other programming environments for Windows or other platforms (at least those that 
natively support OpenGL). The utility library functions are prototyped in a different file, 
glu.h. These files are usually located in a special directory in your include path. For 
example, the following code shows the typical initial header inclusions for a typical 
Windows program that uses OpenGL: 


#include<windows.h> 
#include<gl/gl.h> 
#include<gl/glu.h> 


For the purposes of this book, we have created our own header file OpenGL.h, which has 
macros defined for the various platforms and operating systems to include the correct 
headers and libraries for use with OpenGL. All the sample programs include this source 
file. 


API Specifics 


OpenGL was designed by some clever people who had a lot of experience designing graph- 
ics programming APIs. They applied some standard rules to the way functions were named 
and variables were declared. The API is simple and clean and easy for vendors to extend. 
OpenGL tries to avoid as much policy as possible. Policy refers to assumptions that the 
designers make about how programmers will use the API. Examples of policies are assum- 
ing that you always specify vertex data as floating-point values, assuming that fog is 
always enabled before any rendering occurs, or assuming that all objects in a scene are 
affected by the same lighting parameters. To do so would eliminate many of the popular 
rendering techniques that have developed over time. 


Data Types 

To make it easier to port OpenGL code from one platform to another, OpenGL defines its 
own data types. These data types map to normal C data types that you can use instead, if 
you want. The various compilers and environments, however, have their own rules for the 
size and memory layout of various C variables. By using the OpenGL defined variable 
types, you can insulate your code from these types of changes. 


Table 2.1 lists the OpenGL data types, their corresponding C data types under the 32-bit 
Windows environments (Win32), and the appropriate suffix for literals. In this book, we 
use the suffixes for all literal values. You will see later that these suffixes are also used in 
many OpenGL function names. 
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integer 


TABLE 2.1 OpenGL Variable Types and Corresponding C Data Types 
OpenGL Data Internal Defined as C Cc 
Type Representation Type Literal Suffix 
GLbyte 8-bit integer signed char b 
GLshort 16-bit integer short s 
GLint, GLsizei 32-bit integer long 1 
GLfloat, 32-bit floating float it 
GLclampf point 
GLdouble, 64-bit floating double d 
GLclampd point 
GLubyte, 8-bit unsigned unsigned char ub 
GLboolean integer 
GLushort 16-bit unsigned unsigned short us 

integer 
GLuint, GLenum, 32-bit unsigned unsigned long ui 


All data types start with a GL to denote OpenGL. Most are followed by their corresponding 
C data types (byte, short, int, float, and so on). Some have a u first to denote an 
unsigned data type, such as ubyte to denote an unsigned byte. For some uses, a more 
descriptive name is given, such as size to denote a value of length or depth. For example, 
GLsizei is an OpenGL variable denoting a size parameter that is represented by an integer. 
The clamp designation is a hint that the value is expected to be “clamped” to the range 
0.0-1.0. The GLboolean variables are used to indicate true and false conditions, GLenum for 
enumerated variables, and GLbitfield for variables that contain binary bit fields. 


Pointers and arrays are not given any special consideration. An array of 10 GLshort vari- 
ables is simply declared as 


GLshort shorts[10]; 


and an array of 10 pointers to GLdouble variables is declared with 
GLdouble *doubles[10]; 


Some other pointer object types are used for NURBS and quadrics. They require more 
explanation and are covered in later chapters. 


Function-Naming Conventions 

Most OpenGL functions follow a naming convention that tells you which library the 
function is from and often how many and what types of arguments the function takes. All 
functions have a root that represents the function’s corresponding OpenGL command. For 
example, glColor3f has the root Color. The gi prefix represents the gl library, and the 3f 
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suffix means the function takes three floating-point arguments. All OpenGL functions take 
the following format: 


<Library prefix><Root command><0Optional argument count><Optional argument type> 


Figure 2.4 illustrates the parts of an OpenGL function. This sample function with the 
suffix 3f takes three floating-point arguments. Other variations take three integers 
(glColor3i), three doubles (g1Color3d), and so forth. This convention of adding the 
number and types of arguments (see Table 2.1) to the end of OpenGL functions makes it 
easy to remember the argument list without having to look it up. Some versions of 
glColor take four arguments to specify an alpha component (transparency), as well. 


glColor3f(...) 


a ee 


as 
gllibrary Root command Number of —_ Type of 
arguments arguments 


FIGURE 2.4 A dissected OpenGL function. 


In the reference sections of this book, these “families” of functions are listed by their 
library prefix and root. All the variations of glColor (g1Color8f, glColor4f, glColor3i, 
and so on) are listed under a single entry—glColor. 


Many C/C++ compilers for Windows assume that any floating-point literal value is of type 
double unless explicitly told otherwise via the suffix mechanism. When using literals for 
floating-point arguments, if you don’t specify that these arguments are of type float 
instead of double, the compiler issues a warning while compiling because it detects that 
you are passing a double to a function defined to accept only floats, resulting in a possi- 
ble loss of precision. As OpenGL programs grow, these warnings quickly number in the 
hundreds and make it difficult to find any real syntax errors. You can turn off these warn- 
ings using the appropriate compiler options, but we advise against doing so. It’s better to 
write clean, portable code the first time. So, clean up those warning messages by cleaning 
up the code (in this case, by explicitly using the float type)—not by disabling potentially 
useful warnings. 


Additionally, you might be tempted to use the functions that accept double-precision 
floating-point arguments rather than go to all the bother of specifying your literals as 
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floats. However, OpenGL uses floats internally, and using anything other than the single- 
precision floating-point functions adds a performance bottleneck because the values are 
converted to floats anyway before being processed by OpenGL—not to mention that every 
double takes up twice as much memory as a float. For a program with a lot of numbers 
“floating” around, these performance hits can add up pretty fast! 


Platform Independence 


OpenGL is a powerful and sophisticated API for creating 3D graphics, with more than 300 
commands that cover everything from setting material colors and reflective properties to 
doing rotations and complex coordinate transformations. You might be surprised that 
OpenGL does not have a single function or command relating to window or screen 
management. In addition, there are no functions for keyboard input or mouse interaction. 
Consider, however, that one of the OpenGL designers’ primary goals was platform inde- 
pendence. You create and open a window differently under the various platforms. Even if 
OpenGL did have a command for opening a window, would you use it, or would you use 
the operating system’s own built-in API call? 


Another platform issue is the handling of keyboard and mouse input events under the 
different operating systems and environments. If every environment handled these events 
the same, we would have only one environment to worry about and no need for an 
“open” API. This is not the case, however, and it probably won’t happen within our brief 
lifetimes! So OpenGL’s platform independence comes at the cost of having no OS and GUI 
functions. 


Using GLUT 


In the beginning, there was AUX, the OpenGL auxiliary library. The AUX library was 
created to facilitate the learning and writing of OpenGL programs without the program- 
mer’s being distracted by the minutiae of any particular environment, be it UNIX, 
Windows, or whatever. You wouldn’t write “final” code when using AUX; it was more of a 
preliminary staging ground for testing your ideas. A lack of basic GUI features limited the 
library’s use for building useful applications. 


Only a few years ago, most OpenGL samples circulating the Web (and OpenGL book 
samples!) were written using the AUX library. The Windows implementation of the AUX 
library was buggy and prone to cause frequent crashes. The lack of any GUI features what- 
soever was another drawback in the modern GUI-oriented world. 


AUX has since been replaced by the GLUT library for cross-platform programming exam- 
ples and demonstrations. GLUT stands for OpenGL utility toolkit (not to be confused with 
the standard GLU—OpenGL utility library). Mark Kilgard, while at SGI, wrote GLUT as a 
more capable replacement for the AUX library and included some GUI features to at least 
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make sample programs more usable under X Windows. This replacement includes using 
pop-up menus, managing other windows, and even providing joystick support. GLUT is 
not public domain, but it is free and free to redistribute. The latest GLUT distribution 
available at the time of printing is on the CD that accompanies this book. 


For most of this book, we use GLUT as our program framework. This decision serves two 
purposes. The first is that it makes most of the book accessible to a wider audience than 
only Windows programmers. With a little effort, experienced Linux or Mac programmers 
should be able to set up GLUT for their programming environments and follow along 
most of the examples in this book. Platform-specific details are included in the chapters in 
Part II of this book. 


The second point is that using GLUT eliminates the need to know and understand basic 
GUI programming on any specific platform. Although we explain the general concepts, we 
do not claim to write a book about GUI programming, but about OpenGL. Using GLUT 
for the basic coverage of the API, we make life a bit easier for Windows/Mac/Linux novices 
as well. 


It’s unlikely that all the functionality of a commercial application will be embodied 
entirely in the code used to draw in 3D, so you can’t rely entirely on the GLUT library for 
everything. Nevertheless, the GLUT library excels in its role for learning and demonstra- 
tion exercises. Even for an experienced Windows programmer, it is still easier to employ 
the GLUT library to iron out 3D graphics code before integrating it into a complete appli- 
cation. 


Setting Up Your Programming Environment 

There is no “correct” programming environment for this book. We could not possibly 
cover all the different ways you can configure your compiler and programming environ- 
ment. As we’ve stated before, the purpose of this book is to teach you OpenGL, not how 
to program in C or how to use Visual C++/C++, Project Builder, and so on. If you are not a 
whiz at using your particular environment and tools, look at the platform-specific chapters 
in Part II. There, you will find a quick start guide for each operating system. 


In addition to platform libraries, you will need the header file glut.h. It is located in the 
\tools\glut-3.7\include\GL directory on the CD-ROM. A good place to put this header 
is the same directory where your development environment keeps gl.h and glu.h. 


Your First Program 

To understand the GLUT library better, look at possibly the world’s shortest OpenGL 
program, which was written using the GLUT library. Listing 2.1 presents the SIMPLE 
program. Its output is shown in Figure 2.5. You'll also learn just a few things about 
OpenGL along the way! 
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LISTING 2.1 Source Code for SIMPLE: A Very Simple OpenGL Program 
#include <OpenGL.h> 


TULLLTT TTT LTT TAL LT 
// Called to draw scene 
void RenderScene(void) 
{ 
// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Flush drawing commands 
glFlush(); 
} 


LATTTT TTT TTT TTT Ek 
// Setup the rendering state 
void SetupRC(void) 

{ 

glClearColor(0.0f, 0.0f, 1.0f, 1.0f); 

} 


FITTTTTT TTT TTT TTT TTT TT 
// Main program entry point 
void main(void) 
{ 
glutInitDisplayMode(GLUT_SINGLE | GLUT_RGB) ; 
glutCreateWindow("Simple") ; 
glutDisplayFunc(RenderScene) ; 


SetupRC(); 


glutMainLoop(); 
} 


The SIMPLE program doesn’t do much. When run from the command line (or develop- 
ment environment), it creates a standard GUI window with the caption Simple and a clear 
blue background. If you are running Visual C++, when you terminate the program, you 
see the message Press any key to continue in the console window. You need to press a 
key to terminate the program. This standard feature of the Microsoft IDE for running a 
console application ensures that you can see whatever output your program places 
onscreen (the console window) before the window vanishes. If you run the program from 
the command line, you don’t get this behavior. If you double-click on the program file 
from Explorer, you see the console window, but it vanishes when the program terminates. 
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FIGURE 2.5 Output from the SIMPLE program. 


This simple program contains four GLUT library functions (prefixed with glut) and three 
“real” OpenGL functions (prefixed with g1). Let’s examine the program line by line, after 
which we will introduce some more functions and substantially improve on our first 
example. 


The Header 
Listing 2.1 contains only one include file: 


#include <OpenGL.h> 


This file includes the g1.h and glut.h headers, which bring in the function prototypes 
used by the program. 


The Body 
Next, we skip down to the entry point of all C programs: 


void main(void) 


{ 


Console-mode C and C++ programs always start execution with the function main. If you 
are an experienced Windows nerd, you might wonder where WinMain is in this example. 
It’s not there because we start with a console-mode application, so we don’t have to start 
with window creation and a message loop. With Win32, you can create graphical windows 
from console applications, just as you can create console windows from GUI applications. 
These details are buried within the GLUT library. (Remember, the GLUT library is designed 
to hide just these kinds of platform details.) 


Display Mode: Single Buffered 
The first line of code, shown here, tells the GLUT library what type of display mode to use 
when creating the window: 


glutInitDisplayMode(GLUT_SINGLE | GLUT_RGBA) ; 


51 


52 


CHAPTER 2. Using OpenGL 


The flags here tell it to use a single-buffered window (GLUT_SINGLE) and to use RGBA color 
mode (GLUT_RGBA). A single-buffered window means that all drawing commands are 
performed on the window displayed. An alternative is a double-buffered window, where 
the drawing commands are actually executed on an off-screen buffer and then quickly 
swapped into view on the window. This method is often used to produce animation 
effects and is demonstrated later in this chapter. In fact, we use double-buffered mode for 
the rest of the book. RGBA color mode means that you specify colors by supplying sepa- 
rate intensities of red, green, and blue components. The alternative is color index mode, 
which is now largely obsolete, where you specify colors by using an index into a color 
palette. 


Creating the OpenGL Window 
The next call to the GLUT library actually creates the window on the screen. The follow- 
ing code creates the window and sets the caption to Simple: 


glutCreateWindow("Simple") ; 
The single argument to glutCreateWindow is the caption for the window’s title bar. 


Displaying Callback 
The next line of GLUT-specific code is 


glutDisplayFunc(RenderScene) ; 


This line establishes the previously defined function RenderScene as the display callback 
function, This means that GLUT calls the function pointed to here whenever the window 
needs to be drawn. This call occurs when the window is first displayed or when the 
window is resized or uncovered, for example. This is the place where we put our OpenGL 
rendering function calls. 


Set Up the Context and Go! 
The next line is neither GLUT- nor OpenGL-specific but is a convention that we follow 
throughout the book: 


SetupRC(); 
In this function, we do any OpenGL initialization that should be performed before render- 


ing. Many of the OpenGL states need to be set only once and do not need to be reset 
every time you render a frame (a screen full of graphics). 


The last GLUT function call comes at the end of the program: 
glutMainLoop(); 
This function starts the GLUT framework running. After you define callbacks for screen 


display and other functions (coming up), you turn GLUT loose. glutMainLoop never 
returns after it is called until the program terminates, and needs to be called only once 
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from an application. This function processes all the operating system-specific messages, 
keystrokes, and so on until you terminate the program. 


OpenGL Graphics Calls 
The SetupRC function contains a single OpenGL function call: 


glClearColor(0.0f, 0.0f, 1.0f, 1.0f); 


This function sets the color used for clearing the window. The prototype for this function 
is 
void glClearColor(GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha); 


GLclampf is defined as a float under most implementations of OpenGL. In OpenGL, a 
single color is represented as a mixture of red, green, and blue components. The range for 
each component can vary from 0.0-1.0. This is similar to the Windows specification of 
colors using the RGB macro to create a COLORREF value. The difference is that in Windows 
each color component in a COLORREF can range from 0-255, giving a total of 
256x256x256—or more than 16 million colors. With OpenGL, the values for each compo- 
nent can be any valid floating-point value between 0 and 1, thus yielding a virtually infi- 
nite number of potential colors. Practically speaking, color output is limited on most 
devices to 24 bits (16 million colors). 


Naturally, both Windows and OpenGL take this color value and convert it internally to 
the nearest possible exact match with the available video hardware. 


Table 2.2 lists some common colors and their component values. You can use these values 
with any of the OpenGL color-related functions. 


TABLE 2.2 Some Common Composite Colors 


Composite Red Green Blue 
Color Component Component Component 
Black 0.0 0.0 0.0 
Red 1.0 0.0 0.0 
Green 0.0 1.0 0.0 
Yellow 1.0 1.0 0.0 
Blue 0.0 0.0 1.0 
Magenta 1.0 0.0 1.0 
Cyan 0.0 1.0 1.0 
Dark gray 0.25 0.25 0.25 
Light gray 0.75 0.75 0.75 
Brown 0.60 0.40 0.12 
Pumpkin orange 0.98 0.625 0.12 
~~ Pastehpink—_ 0.98 0.04 0.7 
Barney purple 0.60 0.40 0.70 


White 1.0 1.0 1.0 
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The last argument to g1ClearColor is the alpha component, which is used for blending 
and special effects such as translucence. Translucence refers to an object’s ability to allow 
light to pass through it. Suppose you would like to create a piece of red stained glass, and 
a blue light happens to be shining behind it. The blue light affects the appearance of the 
red in the glass (blue + red = purple). You can use the alpha component value to generate 
a red color that is semitransparent so it works like a sheet of glass; an object behind it 
shows through. There is more to this type of effect than just using the alpha value, and in 
Chapter 6, “More on Color and Materials,” you'll learn more about this topic; until then, 
you should leave the alpha value as 1. 


Clearing the Color Buffer 
All we have done at this point is set OpenGL to use blue for the clearing color. In our 
RenderScene function, we need an instruction to do the actual clearing: 


glClear(GL_COLOR_BUFFER_BIT) ; 


The glClear function clears a particular buffer or combination of buffers. A buffer is a 
storage area for image information. The red, green, and blue components of a drawing are 
usually collectively referred to as the color buffer or pixel buffer. 


More than one kind of buffer (color, depth, stencil, and accumulation) is available in 
OpenGL, and they are covered in more detail later in the book. For the next several chap- 
ters, all you really need to understand is that the color buffer is the place where the 
displayed image is stored internally and that clearing the buffer with g1Clear removes the 
last drawing from the window. 


Flushing That Queue 
The final OpenGL function call comes last: 


glFlush(); 


This line causes any unexecuted OpenGL commands to be executed; we have one at this 
point—g1Clear. 


Internally, OpenGL uses a rendering pipeline that processes commands sequentially. 
OpenGL commands and statements often are queued up until the OpenGL driver 
processes several “commands” at once. This setup improves performance because commu- 
nication with hardware is inherently slow. Making one trip to the hardware with a truck- 
load of data is much faster than making several smaller trips for each command or 
instruction. We’ll discuss this feature of OpenGL’s operation further in Chapter 11, “It’s All 
About the Pipeline: Faster Geometry Throughput.” In the short program in Listing 2.1, the 
glFlush function simply tells OpenGL that it should proceed with the drawing instruc- 
tions supplied thus far before waiting for any more drawing commands. 


SIMPLE might not be the most interesting OpenGL program in existence, but it demon- 
strates the basics of getting a window up using the GLUT library, and it shows how to 
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specify a color and clear the window. Next, we want to spruce up our program by adding 
some more GLUT library and OpenGL functions. 


Drawing Shapes with OpenGL 


The SIMPLE program made an empty window with a blue background. Now, let’s do some 
drawing in the window. In addition, we want to be able to move and resize the window 
and have our rendering code respond appropriately. In Listing 2.2, you can see the modifi- 
cations. Figure 2.6 shows the output of this program (GLRect). 


LISTING 2.2 Drawing a Centered Rectangle with OpenGL 
#include <OpenGL.h> 


FLTTTTTTTT TTT TATA TTL 
// Called to draw scene 
void RenderScene(void) 
{ 
// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Set current drawing color to red 
// R G B 
glColor3f(1.0f, 0.0f, 0.0f); 


// Draw a filled rectangle with current color 
glRectf(-25.0f, 25.0f, 25.0f, -25.0f); 


// Flush drawing commands 
glFlush(); 
} 


TETTTTTTT TTT TTT TAT A 
// Setup the rendering state 
void SetupRC(void) 

{ 

// Set clear color to blue 

glClearColor(0.0f, @.0f, 1.0f, 1.0f); 

} 


TUTTTTTTTT TTT TTT TTT AT 
// Called by GLUT library when the window has chanaged size 
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LISTING 2.2 Continued 


void ChangeSize(GLsizei w, GLsizei h) 


{ 
GLfloat aspectRatio; 


// Prevent a divide by zero 
if(h == 0) 
h= 1; 


// Set Viewport to window dimensions 
glViewport(®, ®, w, h); 


// Reset coordinate system 
glMatrixMode(GL_PROJECTION) ; 
glLoadidentity(); 


// Establish clipping volume (left, right, bottom, top, near, far) 
aspectRatio = (GLfloat)w / (GLfloat)h; 
if (w <= h) 
glOrtho (-100.0, 100.0, -100 / aspectRatio, 100.0 / aspectRatio, 
1.0, -1.0); 
else 
glOrtho (-100.@ * aspectRatio, 100.0 * aspectRatio, 
-100.0, 100.0, 1.0, -1.0); 


glMatrixMode(GL_MODELVIEW) ; 
glLoadidentity(); 
} 


PTTTTLTT TTT TTA ATT TA TTT 
// Main program entry point 
void main(void) 
{ 
glutInitDisplayMode(GLUT_SINGLE | GLUT_RGB) ; 
glutCreateWindow("GLRect") ; 
glutDisplayFunc(RenderScene) ; 
glutReshapeFunc (ChangeSize) ; 


SetupRC(); 


glutMainLoop() ; 
} 


ee TUE UU EE NSUEIES IIS SUISSE SSIES 
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FIGURE 2.6 Output from the GLRect program. 


Drawing a Rectangle 
Previously, all our program did was clear the screen. We’ve now added the following lines 
of drawing code: 


// Set current drawing color to red 
// R G B 
glColor3f(1.0f, 0.0f, 0.0f); 


// Draw a filled rectangle with current color 
glRectf(-25.0f, 25.0f, 25.0f, -25.0f); 


These lines set the color used for future drawing operations (lines and filling) with the call 
to glColor3f. Then glRectf draws a filled rectangle. 


The g1Color3f function selects a color in the same manner as glClearColor, but no alpha 
translucency component needs to be specified (the default value for alpha is 1.0 for 
completely opaque): 


void glColor3f(GLfloat red, GLfloat green, GLfloat blue); 
The glRectf function takes floating-point arguments, as denoted by the trailing f. The 
number of arguments is not used in the function name because all glRect variations take 


four arguments. The four arguments of glRectf, shown here, represent two coordinate 
pairs—(x1, yl) and (x2, y2): 


void glRectf(GLfloat x7, GLfloat y7, GLfloat x2, GLfloat y2); 
The first pair represents the upper-left corner of the rectangle, and the second pair repre- 
sents the lower-right corner. 


How does OpenGL map these coordinates to actual window positions? This is done in the 
callback function ChangeSize. This function is set as the callback function for whenever 
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the window changes size (when it is stretched, maximized, and so on). This is set by the in 
the same way that the display callback function is set: 


glutReshapeFunc (ChangeSize) ; 
Any time the window size or dimensions change, you need to reset the coordinate system. 


Scaling to the Window 

In nearly all windowing environments, the user can at any time change the size and 
dimensions of the window. Even if you are writing a game that always runs in full-screen 
mode, the window is still considered to change size once—when it is created. When this 
happens, the window usually responds by redrawing its contents, taking into considera- 
tion the window’s new dimensions. Sometimes, you might want to simply clip the 
drawing for smaller windows or display the entire drawing at its original size in a larger 
window. For our purposes, we usually want to scale the drawing to fit within the window, 
regardless of the size of the drawing or window. Thus, a very small window would have a 
complete but very small drawing, and a larger window would have a similar but larger 
drawing. You see this effect in most drawing programs when you stretch a window as 
opposed to enlarging the drawing. Stretching a window usually doesn’t change the 
drawing size, but magnifying the image makes it grow. 


Setting the Viewport and Clipping Volume 

We have already discussed how the viewport and viewing volume affect the coordinate 
range and scaling of 2D and 3D drawings in a 2D window on the computer screen. Now, 
we examine the setting of viewport and clipping volume coordinates in OpenGL. 


Although our drawing is a 2D flat rectangle, we are actually drawing in a 3D coordinate 
space. The glRectf function draws the rectangle in the xy plane at z = 0. Your perspective 
is along the positive z-axis to see the square rectangle at z = 0. (If you’re feeling lost here, 
review this material in Chapter 1, “Introduction to 3D Graphics and OpenGL.”) 


Whenever the window size changes, the viewport and clipping volume must be redefined 
for the new window dimensions. Otherwise, you see an effect like the one shown in Figure 
2.7, where the mapping of the coordinate system to screen coordinates stays the same 
regardless of the window size. 


Because window size changes are detected and handled differently under various environ- 
ments, the GLUT library provides the function glutReshapeFunc, which registers a call- 
back that the GLUT library will call whenever the window dimensions change. The 
function you pass to glutReshapeFunc is prototyped like this: 


void ChangeSize(GLsizei w, GLsizei h); 


We have chosen ChangeSize as a descriptive name for this function, and we will use that 
name for our future examples. 
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FIGURE 2.7 __ Effects of changing window size, but not the coordinate system. 


The ChangeSize function receives the new width and height whenever the window size 
changes. We can use this information to modify the mapping of our desired coordinate 
system to real screen coordinates, with the help of two OpenGL functions: glViewport 
and gl0rtho. 


Defining the Viewport 

To understand how the viewport definition is achieved, let’s look more carefully at the 
ChangeSize function. It first calls g1Viewport with the new width and height of the 
window. The glViewport function is defined as 


void glViewport(GLint x, GLint y, GLsizei width, GLsizei height); 


The x and y parameters specify the lower-left corner of the viewport within the window, 
and the width and height parameters specify these dimensions in pixels. Usually, x and y 
are both 0, but you can use viewports to render more than one drawing in different areas 
of a window. The viewport defines the area within the window in actual screen coordi- 
nates that OpenGL can use to draw in (see Figure 2.8). The current clipping volume is 
then mapped to the new viewport. If you specify a viewport that is smaller than the 
window coordinates, the rendering is scaled smaller, as you see in Figure 2.8. 
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glViewport(0,0,250,250) 
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Window and viewport are same Viewport 1/2 size of window 
FIGURE 2.8 Viewport-to-window mapping. 


Defining the Clipped Viewing Volume 

The last requirement of our ChangeSize function is to redefine the clipping volume so that 
the aspect ratio remains square. The aspect ratio is the ratio of the number of pixels along 
a unit of length in the vertical direction to the number of pixels along the same unit of 
length in the horizontal direction. An aspect ratio of 1.0 defines a square aspect ratio. An 
aspect ratio of 0.5 specifies that for every two pixels in the horizontal direction for a unit 
of length, there is one pixel in the vertical direction for the same unit of length. 


If you specify a viewport that is not square and it is mapped to a square clipping volume, 
the image will be distorted. For example, a viewport matching the window size and 
dimensions but mapped to a square clipping volume would cause images to appear tall 
and thin in tall and thin windows and wide and short in wide and short windows. In this 
case, our square would appear square only when the window was sized to be a square. 


In our example, an orthographic projection is used for the clipping volume. The OpenGL 
command to create this projection is gl0rtho: 


void glOrtho(GLdouble left, GLdouble right, GLdouble bottom, 
GLdouble top, GLdouble near, GLdouble far ); 


In 3D Cartesian space, the left and right values specify the minimum and maximum 
coordinate value displayed along the x-axis; bottom and top are for the y-axis. The near 
and far parameters are for the z-axis, generally with negative values extending away from 
the viewer (see Figure 2.9). Many drawing and graphics libraries use window coordinates 
(pixels) for drawing commands. Using a real floating-point (and seemingly arbitrary) coor- 
dinate system for rendering is one of the hardest things for many beginners to get used to. 
After you work through a few programs, though, it quickly becomes second nature. 
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FIGURE 2.9 Cartesian space. 


Just before the code using glOrtho, notice these two function calls: 


// Reset coordinate system 
glMatrixMode(GL_PROJECTION) ; 
glLoadidentity(); 


The subject of matrices and the OpenGL matrix stacks comes up in Chapter 4, “Geometric 
Transformations: The Pipeline,” where we discuss this topic in more detail. The projection 
matrix is the place where you actually define your viewing volume. The single call to 
glLoadIdentity is needed because gl0rtho doesn’t really establish the clipping volume, 
but rather modifies the existing clipping volume. It multiplies the matrix that describes 
the current clipping volume by the matrix that describes the clipping volume described in 
its arguments. For now, you just need to know that glLoadIdentity serves to “reset” the 
coordinate system before any matrix manipulations are performed. Without this “reset,” 
every time gl0rtho is called, each successive call to glOrtho could result in a further 
corruption of the intended clipping volume, which might not even display the rectangle. 


The last two lines of code, shown here, tell OpenGL that all future transformations will 
affect our models (what we draw): 


glMatrixMode(GL_MODELVIEW) ; 
glLoadiIdentity(); 


We purposely do not cover model transformation until Chapter 4. You do need to know 
now, however, how to set up these things with their default values. Otherwise, if you 
become adventurous and start experimenting, your output might not match what you 
expect. 
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Keeping a Square Square 
The following code does the actual work of keeping our “square” square: 


// Establish clipping volume (left, right, bottom, top, near, far) 
aspectRatio = (GLfloat)w / (GLfloat)h; 
if (w <= h) 
glOrtho (-100.0, 100.0, -100 / aspectRatio, 100.0 / aspectRatio, 
1.0, -1.0); 
else 
glOrtho (-100.0 * aspectRatio, 100.0 * aspectRatio, 
-100.0, 100.0, 1.0, -1.0); 


Our clipping volume (visible coordinate space) is modified so that the left side is always at 
x =-100 and the right side extends to 100 unless the window is wider than it is tall. In 
that case, the horizontal extent is scaled by the aspect ratio of the window. In the same 
manner, the bottom is always at y = -100 and extends upward to 100 unless the window is 
taller than it is wide. In that case, the upper coordinate is also scaled by the aspect ratio. 
This serves to keep a square coordinate region 200x200 available (with 0,0 in the center) 
regardless of the shape of the window. Figure 2.10 shows how this works. 


FIGURE 2.10 Clipping region for three different windows. 


Animation with OpenGL and GLUT 


So far, we’ve discussed the basics of using the GLUT library for creating a window and 
using OpenGL commands for the actual drawing. You will often want to move or rotate 
your images and scenes, creating an animated effect. Let’s take the previous example, 
which draws a square, and make the square bounce off the sides of the window. You could 
create a loop that continually changes your object’s coordinates before calling the 
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RenderScene function. This would cause the square to appear to move around within the 
window. 


The GLUT library enables you to register a callback function that makes it easier to set up 
a simple animated sequence. This function, glutTimerFunc, takes the name of a function 
to call and the amount of time to wait before calling the function: 


void glutTimerFunc(unsigned int msecs, void (*func)(int value), int value); 


This code sets up GLUT to wait msecs milliseconds before calling the function func. You 
can pass a user-defined value in the value parameter. The function called by the timer has 
the following prototype: 


void TimerFunction(int value) ; 


Unlike the Windows timer, this function is fired only once. To effect a continuous anima- 
tion, you must reset the timer again in the timer function. 


In our GLRect program, we can change the hard-coded values for the location of our 
rectangle to variables and then constantly modify those variables in the timer function. 
This causes the rectangle to appear to move across the window. Let’s look at an example of 
this kind of animation. In Listing 2.3, we modify Listing 2.2 to bounce around the square 
off the inside borders of the window. We need to keep track of the position and size of the 
rectangle as we go along and account for any changes in window size. 


LISTING 2.3 Animated Bouncing Square 
#include <OpenGL.h> 


// Initial square position and size 
GLfloat x1 = 0.0f; 

GLfloat y1 = 0.0f; 

GLfloat rsize = 25; 


// Step size in x and y directions 

// (number of pixels to move each time) 
GLfloat xstep = 1.0f; 

GLfloat ystep = 1.0f; 


// Keep track of windows changing width and height 
GLfloat windowidth; 
GLfloat windowHeight; 


TULTLTTTT TTT TTT A TL 
// Called to draw scene 
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LISTING 2.3 Continued 


void RenderScene(void) 
{ 
// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Set current drawing color to red 
// R G B 
glColor3f(1.0f, @.0f, 0.0f); 


// Draw a filled rectangle with current color 
glRectf(x1, y1, x1 + rsize, y1 - rsize); 


// Flush drawing commands and swap 
glutSwapBuffers() ; 
} 


LUTTLTL TTT TTT TTT TT TTL 
// Called by GLUT library when idle (window not being 
// resized or moved) 
void TimerFunction(int value) 
{ 
// Reverse direction when you reach left or right edge 
if (x1 > windowidth-rsize || x1 < -windowidth) 
xstep = -xstep; 


// Reverse direction when you reach top or bottom edge 
if(y1 > windowHeight || y1 < -windowHeight + rsize) 
ystep = -ystep; 


// Actually move the square 
x1 += xstep; 
yi += ystep; 


// Check bounds. This is in case the window is made 
// smaller while the rectangle is bouncing and the 
// rectangle suddenly finds itself outside the new 
// clipping volume 
if (x1 > (windowidth-rsize + xstep)) 

x1 = windowidth-rsize-1; 
else if(x1 < -(windowWidth + xstep) 
x1 = - windowsWidth -1; 
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LISTING 2.3 Continued 


if(y1 > (windowHeight + ystep) ) 

y1 = windowHeight-1; 
else if(y1 < -(windowHeight - rsize + ystep)) 
y1 = -windowHeight + rsize -1; 


// Redraw the scene with new coordinates 
glutPostRedisplay(); 
glutTimerFunc(33,TimerFunction, 1); 


} 


FUTTTLTTTT TTT TTT TTT 
// Setup the rendering state 
void SetupRC(void) 

{ 

// Set clear color to blue 

glClearColor(0.0f, 0.0f, 1.0f, 1.0f); 

} 


FTLTTTTTT TTT TTT TTT TTT TT TAD 
// Called by GLUT library when the window has changed size 
void ChangeSize(GLsizei w, GLsizei h) 

{ 

GLfloat aspectRatio; 


// Prevent a divide by zero 
if(h == Q) 
h= 1; 


// Set Viewport to window dimensions 
glViewport(@, ®, w, h); 


// Reset coordinate system 
glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 


// Establish clipping volume (left, right, bottom, top, near, far) 
aspectRatio = (GLfloat)w / (GLfloat)h; 
if (w <= h) 
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LISTING 2.3 Continued 
{ 
windowidth = 100; 
windowHeight = 100 / aspectRatio; 
glOrtho (-100.0, 100.0, -windowHeight, windowHeight, 1.0, -1.0); 
} 
else 
{ 
windowidth = 100 * aspectRatio; 
windowHeight = 100; 
glOrtho (-windowidth, windowidth, -100.0, 100.0, 1.0, -1.0); 
} 


glMatrixMode (GL_MODELVIEW) ; 
glLoadidentity(); 
} 


FETTTLTTTTT TTT ATTA TTT TT hk 
// Main program entry point 
void main(void) 
{ 
glutInitDisplayMode(GLUT_DOUBLE | GLUT_RGB) ; 
glutCreateWindow("Bounce") ; 
glutDisplayFunc(RenderScene) ; 
glutReshapeFunc(ChangeSize) ; 
glutTimerFunc(33, TimerFunction, 1); 


SetupRC() ; 


glutMainLoop(); 
} 


Double-Buffering 

One of the most important features of any graphics packages is support for double 
buffering. This feature allows you to execute your drawing code while rendering to an 
offscreen buffer. Then a swap command places your drawing onscreen instantly. 


Double buffering can serve two purposes. The first is that some complex drawings might 
take a long time to draw, and you might not want each step of the image composition to 
be visible. Using double buffering, you can compose an image and display it only after it is 
complete. The user never sees a partial image; only after the entire image is ready is it 
shown onscreen. 
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A second use for double buffering is animation. Each frame is drawn in the offscreen 
buffer and then swapped quickly to the screen when ready. The GLUT library supports 
double-buffered windows. In Listing 2.3 note the following line: 


glutInitDisplayMode(GLUT_DOUBLE | GLUT_RGB) ; 


We have changed GLUT_SINGLE to GLUT_DOUBLE. This change causes all the drawing code to 
render in an offscreen buffer. 


Next, we also changed the end of the RenderScene function: 


// Flush drawing commands and swap 
glutSwapBuffers(); 
} 


No longer are we calling glFlush. This function is no longer needed because when we 
perform a buffer swap, we are implicitly performing a flush operation. 


These changes cause a smoothly animated bouncing rectangle, shown in Figure 2.11. The 
function glutSwapBuffers still performs the flush, even if you are running in single- 
buffered mode. Simply change GLUT_DOUBLE back to GLUT_SINGLE in the bounce sample to 
see the animation without double buffering. As you'll see, the rectangle constantly blinks 
and stutters, a very unpleasant and poor animation with single buffering. 


FIGURE 2.11 Follow the bouncing square. 


The GLUT library is a reasonably complete framework for creating sophisticated sample 
programs and perhaps even full-fledged commercial applications (assuming you do not 
need to use OS-specific or GUI features). It is not the purpose of this book to explore 
GLUT in all its glory and splendor, however. Here and in the reference section to come, we 
restrict ourselves to the small subset of GLUT needed to demonstrate the various features 
of OpenGL. 
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The OpenGL State Machine 


Drawing 3D graphics is a complicated affair. In the chapters ahead, we will cover many 
OpenGL functions. For a given piece of geometry, many things can affect how it is drawn. 
Is a light shining on it? What are the properties of the light? What are the properties of 
the material? Which, if any, texture should be applied? The list could go on and on. 


We call this collection of variables the state of the pipeline. A state machine is an abstract 
model of a collection of state variables, all of which can have various values, be turned on 
or off, and so on. It simply is not practical to specify all the state variables whenever we 
try to draw something in OpenGL. Instead, OpenGL employs a state model, or state 
machine, to keep track of all the OpenGL state variables. When a state value is set, it 
remains set until some other function changes it. Many states are simply on or off. 
Lighting, for example (see Chapter 11), is either turned on or off. Geometry drawn 
without lighting is drawn without any lighting calculations being applied to the colors set 
for the geometry. Any geometry drawn after lighting is turned back on is then drawn with 
the lighting calculations applied. 


To turn these types of state variables on and off, you use the following OpenGL function: 


void glEnable(GLenum capability) ; 


You turn the variable back off with the corresponding function: 


void glDisable(GLenum capability); 


For the case of lighting, for instance, you can turn it on by using the following: 


glEnable(GL_LIGHTING) ; 


And you turn it back off with this function: 
glDisable(GL_LIGHTING) ; 


If you want to test a state variable to see whether it is enabled, OpenGL again has a conve- 
nient mechanism: 


Glboolean glIsEnabled(GLenum capability) ; 


Not all state variables, however, are simply on or off. Many of the OpenGL functions yet 
to come set up values that “stick” until changed. You can query what these values are at 
any time as well. A set of query functions allows you to query the values of booleans, inte- 
gers, floats, and double variables. These four functions are prototyped thus: 


void glGetBooleanv(GLenum pname, GLboolean *params) ; 
void glGetDoublev(GLenum pname, GLdouble *params) ; 
void glGetFloatv(GLenum pname, GLfloat *params) ; 
void glGetIntegerv(GLenum pname, GLint *params) ; 
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Each function returns a single value or a whole array of values, storing the results at the 
address you supply. The various parameters are documented in the reference section (there 
are a lot of them!). Most may not make much sense to you right away, but as you progress 
through the book, you will begin to appreciate the power and simplicity of the OpenGL 
state machine. 


Saving and Restoring States 

OpenGL also has a convenient mechanism for saving a whole range of state values and 
restoring them later. The stack is a convenient data structure that allows values to be 
pushed on the stack (saved) and popped off the stack later to retrieve them. Items are 
popped off in the opposite order in which they were pushed on the stack. We call this a 
Last In First Out (LIFO) data structure. It’s an easy way to just say, “Hey, please save this” 
(push it on the stack), and then a little later say, “Give me what I just saved” (pop it off 
the stack). You’ll see that the concept of the stack plays a very important role in matrix 
manipulation when you get to Chapter 4. 


A single OpenGL state value or a whole range of related state values can be pushed on the 
attribute stack with the following command: 


void glPushAttrib(GLbitfield mask); 


Values are correspondingly retrieved with this command: 


void glPopAttrib(GLbitfield mask); 


Note that the argument to these functions is a bitfield. This means that you use a bitwise 
mask, which allows you to perform a bitwise OR (in C using the | operator) of multiple 
state values with a single function call. For example, you could save the lighting and 
texturing state with a single call like this: 


glPushAttrib(GL_TEXTURE_BIT | GL_LIGHTING BIT); 


A complete list of all the OpenGL state values that can be saved and restored with these 
functions is located in the reference sections. 


OpenGL Errors 


In any project, you want to write robust and well-behaved programs that respond politely 
to their users and have some amount of flexibility. Graphical programs that use OpenGL 
are no exception, and if you want your programs to run smoothly, you need to account 
for errors and unexpected circumstances. OpenGL provides a useful mechanism for you to 
perform an occasional sanity check in your code. This capability can be important 
because, from the code’s standpoint, it’s not really possible to tell whether the output was 
the Space Station Freedom or the Space Station Melted Crayon! 
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When Bad Things Happen to Good Code 

Internally, OpenGL maintains a set of six error flags. Each flag represents a different type 
of error. Whenever one of these errors occurs, the corresponding flag is set. To see whether 
any of these flags are set, call g1GetError: 


Glenum glGetError(void); 


The glGetError function returns one of the values listed in Table 2.3. The GLU library 
defines three errors of its own, but these errors map exactly to two flags already present. If 
more than one of these flags is set, glGetError still returns only one distinct value. This 
value is then cleared when glGetError is called, and glGetError again will return either 
another error flag or GL_NO_ERROR. Usually, you want to call g1GetError in a loop that 
continues checking for error flags until the return value is GL_NO_ERROR. 


You can use another function in the GLU library, gluErrorString, to get a string describ- 
ing the error flag: 


const GLubyte* gluErrorString(GLenum errorCode) ; 
This function takes as its only argument the error flag (returned from glGetError) and 


returns a static string describing that error. For example, the error flag GL_INVALID_ENUM 
returns this string: 


invalid enumerant 


TABLE 2.3 OpenGL Error Codes 


Error Code Description 

GL_INVALID_ENUM The enum argument is out of range. 
GL_INVALID_VALUE The numeric argument is out of range. 
GL_INVALID_OPERATION _ The operation is illegal in its current state. 
GL_STACK_OVERFLOW The command would cause a stack overflow. 
GL_STACK_UNDERFLOW The command would cause a stack underflow. 
GL_OUT_OF_MEMORY Not enough memory is left to execute the command. 
GL_TABLE_TOO_LARGE The specified table is too large 

GL_NO_ERROR No error has occurred. 


You can take some peace of mind from the assurance that if an error is caused by an 
invalid call to OpenGL, the command or function call is ignored. The only exceptions to 
this are the functions (described in later chapters) that take pointers to memory (that may 
cause a program to crash if the pointer is invalid) and the out of memory condition. If you 
receive an out of memory error, all bets are off as to what you might see onscreen! 
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Identifying the Version 


As mentioned previously, sometimes you want to take advantage of a known behavior in a 
particular implementation. If you know for a fact that you are running on a particular 

vendor's graphics card, you may rely on some known performance characteristics to 

enhance your program. You may also want to enforce some minimum version number for 
particular vendors’ drivers. What you need is a way to query OpenGL for the vendor and ne 
version number of the rendering engine (the OpenGL driver). Both the GL library and 

GLU library can return version and vendor-specific information about themselves. 


For the GL library, you can call glGetString: 


const GLubyte *glGetString(GLenum name) ; 


This function returns a static string describing the requested aspect of the GL library. The 
valid parameter values are listed under glGetString in the reference section, along with 
the aspect of the GL library they represent. 


The GLU library has a corresponding function, gluGetString: 


const GLubyte *gluGetString(GLenum name); 


It returns a string describing the requested aspect of the GLU library. The valid parameters 
are listed under gluGetString in the reference section, along with the aspect of the GLU 
library they represent. 


Getting a Clue with glHint 


There is more than one way to skin a cat; so goes the old saying. The same is true with 3D 
graphics algorithms. Often a trade-off must be made for the sake of performance, or 
perhaps if visual fidelity is the most important issue, performance is less of a considera- 
tion. Often an OpenGL implementation may contain two ways of performing a given 
task—a fast way that compromises quality slightly and a slower way that improves visual 
quality. The function glHint allows you to specify certain preferences of quality or speed 
for different types of operations. The function is defined as follows: 


void glHint(GLenum target, GLenum mode) ; 


The target parameter allows you to specify types of behavior you want to modify. These 
values, listed under glHint in the reference section, include hints for fog and antialiasing 
accuracy. The mode parameter tells OpenGL what you care most about—faster render time 
and nicest output, for instance—or that you don’t care (the only way to get back to the 
default behavior). Be warned, however, that all implementations are not required to honor 
calls into glHint; it’s the only function in OpenGL whose behavior is intended to be 
entirely vendor-specific. 
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Using Extensions 


With OpenGL being a “standard” API, you might think that hardware vendors are able to 
compete only on the basis of performance and perhaps visual quality. However, the field 
of 3D graphics is very competitive, and hardware vendors are constantly innovating, not 
just in the areas of performance and quality, but in graphics methodologies and special 
effects. OpenGL allows vendor innovation through its extension mechanism. This mecha- 
nism works in two ways. First, vendors can add new functions to the OpenGL API that 
developers can use. Second, new tokens or enumerants can be added that will be recog- 
nized by existing OpenGL functions such as glEnable. 


Making use of new enumerants or tokens is simply a matter of adding a vendor-supplied 
header file to your project. Vendors must register their extensions with the OpenGL ARB, 
thus keeping one vendor from using a value used by someone else. Conveniently, there is 
a header file glext.h (supplied on the CD-ROM) that includes the most common exten- 
sions. 


Checking for an Extension 

Gone are the days when games would be recompiled for a specific graphics card. You have 
already seen that you can check for a string identifying the vendor and version of the 
OpenGL driver. You can also get a string that contains identifiers for all OpenGL exten- 
sions supported by the driver. One line of code returns a character array of extension 
names: 


const char *szExtensions = glGetString(GL_EXTENSIONS) ; 


This string contains the space-delimited names of all extensions supported by the driver. 
You can then search this string for the identifier of the extension you want to use. For 
example, you might do a quick search for a Windows-specific extension like this: 


if (strstr(extensions, "WGL_EXT_swap_control" != NULL) ) 
{ 
wglSwapIntervalEXT = 
(PFNWGLSWAPINTERVALEXTPROC) wglGetProcAddress("wglSwapIntervalExT") ; 


if (wglSwapIntervalEXT != NULL) 
wglSwapIntervalEXT(1) ; 
} 


If you use this method, you should also make sure that the character following the name 
of the extension is either a space or a NULL. What if, for example, this extension is 
superceded by the WGL_EXT_swap_control2 extension? In this case, the C runtime function 
strstr would still find the first string, but you may not be able to assume that the second 
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extension behaves exactly like the first. A more robust toolkit function is included in the 
file IsExtSupported.c in the \common directory on the CD-ROM: 


int gltIsExtSupported(const char *extension) ; 


This function returns 1 if the named extension is supported or 0 if it is not. The \common 
directory contains a whole set of helper and utility functions for use with OpenGL, and 
many are used throughout this book. All the functions are prototyped in the file 
gltools.h. 


This example also shows how to get a pointer to a new OpenGL function under Windows. 
The windows function wg1GetProcAddress returns a pointer to an OpenGL function 
(extension) name. Getting a pointer to an extension varies from OS to OS and will be 
dealt with in more detail in Part II of this book. This Windows-specific extension and the 
typedef (PFNWGLSWAPINTERVALEXTPROC) for the function type is located in the wglext.h 
header file, also included on the CD-ROM. We also discuss this particular important exten- 
sion in Chapter 13, “Wiggle: OpenGL on Windows.” 


In the meantime, again the gltools library comes to the rescue with the following func- 
tion: 


void *gltGetExtensionPointer(const char *szExtensionName) ; 


This function provides a platform-independent wrapper that returns a pointer to the 
named OpenGL extension. The implementation of this function is in the file 
GetExtensionPointer.c, which you will have to add to your projects to make use of this 
feature. 


Who's Extension Is This? 

Using OpenGL extensions, you can provide code paths in your code to improve rendering 
performance and visual quality or even add special effects that are supported only by a 
particular vendor’s hardware. But who owns an extension? That is, which vendor created 
and supports a given extension? You can usually tell just by looking at the extension 
name. Each extension has a three-letter prefix that identifies the source of the extension. 
Table 2.4 provides a sampling of extension identifiers. 


TABLE 2.4 A Sampling of OpenGL Extension Prefixes 


Prefix Vendor 

SGI_ Silicon Graphics 
ATI_ ATI Technologies 
NV_ NVidia 

IBM_ IBM 

WGL_ Microsoft 

EXT_ Cross-Vendor 


ARB_ ARB Approved 
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It is not uncommon for one vendor to support another vendor’s extension. For example, 
some NVidia extensions are widely popular and supported on ATI hardware. When this 
happens, the competing vendor must follow the original vendor’s specification (details on 
how the extension is supposed to work). Frequently, everyone agrees that the extension is 
a good thing to have, and the extension has an EXT_ prefix to show that it is (supposed) to 
be vendor neutral and widely supported across implementations. 


Finally, we also have ARB-approved extensions. The specification for these extensions has 
been reviewed (and argued about) by the OpenGL ARB. These extensions usually signal 
the final step before some new technique or function finds its way into the core OpenGL 
specification. We expound upon the idea of the core OpenGL API versus the OpenGL 
extensions in greater detail in Part III of this book. 


Getting to OpenGL Beyond 1.1 on Windows 

Most Windows programmers use the Microsoft development tools, meaning Visual C++ or 
the newer Visual C++ .NET development environments. The Microsoft software OpenGL 
implementation for Windows includes only functions and tokens for OpenGL as defined 
in the OpenGL specification version 1.1. Since that time, we have seen 1.2, 1.3, 1.4, 1.5, 
and 2.0. This means several OpenGL features are unavailable to users of the OpenGL 
header files included with Microsoft’s development tools. Other OS vendors and tool 
makers have managed to keep more up to date, however, and the Macintosh OS X and 
Linux samples should compile with fewer problems. 


Nevertheless, OpenGL can at times seem like a moving target, especially where cross- 
platform compatibility interacts with the later and new enhancements to OpenGL. The 
header file glext.h, included in the \common directory, contains constants and function 
prototypes for most OpenGL functionality past version 1.1 and is already a part of the 
standard development tools on some platforms. This header is included specifically for 
Windows developers, whereas Mac developers, for example, will use the glext.h headers 
included with the XCode or Project Workbench development environments. 


Between the glext.h header file and the gltGetExtensionPointer function in gltools, it 
will not be difficult for you to build the samples in this book and run them with a wide 
variety of compilers and development environments. 


Summary 


We covered a lot of ground in this chapter. We introduced you to OpenGL, told you a 
little bit about its history, introduced the OpenGL utility toolkit (GLUT), and presented 
the fundamentals of writing a program that uses OpenGL. Using GLUT, we showed you 
the easiest possible way to create a window and draw in it using OpenGL commands. You 
learned to use the GLUT library to create windows that can be resized, as well as create a 
simple animation. You were also introduced to the process of using OpenGL to do 
drawing—composing and selecting colors, clearing the screen, drawing a rectangle, and 
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setting the viewport and clipping volume to scale images to match the window size. We 
discussed the various OpenGL data types and the headers required to build programs that 
use OpenGL. 


With a little coding finally under your belt, you were ready to dive into some other ideas 
that you need to be familiar with before you move forward. The OpenGL state machine 
underlies almost everything you do from here on out, and the extension mechanism will 
make sure you can access all the OpenGL features supported by your hardware driver, 
regardless of your development tool. You also learned how to check for OpenGL errors 
along the way to make sure you aren’t making any illegal state changes or rendering 
commands. With this foundation, you can move forward to the chapters ahead. 
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glClearColor 


Purpose: Sets the color and alpha values to use for clearing the color buffers. 
Include File: <gl.h> 

Syntax: 

void glClearColor(GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha); 


Description: This function sets the fill values to be used when clearing the red, green, 
blue, and alpha buffers (jointly called the color buffer). The values speci- 
fied are clamped to the range [0.0f, 1.0f]. 


Parameters: 

red GLclampf: The red component of the fill value. 
green GLclampf: The green component of the fill value. 
blue GLclampf: The blue component of the fill value. 
alpha GLclampf: The alpha component of the fill value. 
Returns: None. 


glDisable, glEnable 


Purpose: Disables or enables an OpenGL state feature. 
Include File: <GL/gl.h> 
Syntax: 


void glDisable(GLenum feature) ; 
glEnable 
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Description: glDisable disables an OpenGL drawing feature, and glEnable enables an 
OpenGL drawing feature. 

Parameters: 

feature GLenum: The feature to disable or enable. A complete list of states is given 
in the OpenGL specification and grows regularly with new revisions 
from the ARB and new OpenGL extensions from hardware vendors. For 
illustration, Table 2.5 lists a small sampling of states that are turned on 


and off. 
TABLE 2.5 Features Enabled/Disabled by glEnable/g1Disable 
Feature Description 
GL_BLEND Color blending 
GL_CULL_FACE Polygon culling 
GL_DEPTH_TEST Depth test 
GL_DITHER Dithering 
GL_FOG OpenGL fog mode 
GL_LIGHTING OpenGL lighting 
GL_LIGHTx xth OpenGL light (minimum: 8) 
GL_POINT_SMOOTH Point antialiasing 
GL_LINE_SMOOTH Line antialiasing 
GL_LINE_STIPPLE Line stippling 
GL_POLYGON_SMOOTH Polygon antialiasing 
GL_SCISSOR_TEST Scissoring enabled 
GL_STENCIL_TEST Stencil test 
GL_TEXTURE_xD xD texturing (1, 2, or 3) 
GL_TEXTURE_CUBE_MAP Cube map texturing 
GL_TEXTURE_GEN_x Texgen for x (S, T, R, or Q) 
Returns: None. 
See Also: glIsEnabled, glPopAttrib, glPushAttrib 
glFinish 
Purpose: Forces all previous OpenGL commands to complete. 
Syntax: 


void glFinish(void) ; 


Description: OpenGL commands are usually queued and executed in batches to opti- 
mize performance. The glFinish command forces all pending OpenGL 
commands to be executed. Unlike g1Flush, this function does not return 
until all the rendering operations have been completed. 
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Returns: None. 

See Also: glFlush(); 

glFlush 

Purpose: Flushes OpenGL command queues and buffers. 
Syntax: 


void glFlush(void) ; 


Description: OpenGL commands are usually queued and executed in batches to opti- 
mize performance. This can vary among hardware, drivers, and OpenGL 
implementations. The glFlush command causes any waiting commands 
to be executed. This must be accomplished “in finite time.” This is essen- 
tially the same as asynchronous execution of the graphics commands 
because g1Flush returns immediately. 


Returns: None. 

See Also: glFinish 

glGetXxxxv 

Purpose: Retrieves a numeric state value or array of values. 
Variations: 


void glGetBooleanv(GLenum value, Glboolean *data); 
void glGetIntegerv(GLenum value, int *data); 
void glGetFloatv(GLenum value, float *data); 
void glGetDoublev(GLenum value, float *data); 


Description: Many OpenGL state variables are completely identified by symbolic 
constants. The values of these state variables can be retrieved with the 
glGetXxxxv commands. The complete list of OpenGL state values is more 
than 28 pages long and can be found in Table 6.6 of the OpenGL specifi- 
cation included on the CD-ROM. 


Returns: Fills in the supplied buffer with the OpenGL state information. 
glGetError 

Purpose: Checks for OpenGL errors. 

Syntax: 


GLenum glGetError(void) ; 
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Description: This function returns one of the OpenGL error codes listed in Table 2.3. 
Error codes are cleared when checked, and multiple error flags may be 
currently active. To retrieve all errors, call this function repeatedly until it 
return GL_NO_ERROR. 


Returns: One of the OpenGL error codes listed in Table 2.3. 
glGetString 

Purpose: Retrieves descriptive strings about the OpenGL implementation. 
Syntax: 


const GLubyte* glGetString(GLenum name) ; 


Description: This function returns a character array describing some aspect of the 
current OpenGL implementation. The parameter GL_VENDOR returns the 
name of the vendor. GL_RENDERER is implementation dependent and may 
contain a brand name or the name of the vendor. GL_VERSION returns the 
version number followed by a space and any vendor-specific information. 
GL_EXTENSIONS returns a list of space-separated extension names 
supported by the implementation. 


Returns: A constant byte array (character string) containing the requested string. 
glHint 

Purpose: Allows optional control of certain rendering behaviors. 

Syntax: 


void glHint(GLenum target, GLenum hint); 


Description: Certain aspects of GL behavior may be controlled with hints. Valid hints 
are GL_NICEST, GL_FASTEST, and GL_DONT_CARE. Hints allow the program- 
mers to specify whether they care more about rendering quality 
(GL_NICEST), performance (GL_FASTEST), or use the default for the imple- 
mentation (GL_DONT_CARE). 


GL_PERSPECTIVE_CORRECTION_HINT—Desired quality of parameter 
interpolation 


GL_POINT_SMOOTH_HINT—Desired sampling quality of points 
GL_LINE_SMOOTH_HINT—Desired sampling quality of lines 
GL_POLYGON_SMOOTH_HINT—Desired sampling quality of polygons 


GL_FOG_HINT—Calculate fog by vertex (GL_FASTEST) or per pixel 
(GL_NICEST) 
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GL_GENERATE_MIPMAP_HINT—Quality and performance of automatic 
mipmap-level generation 


GL_TEXTURE_COMPRESSION_HINT—Quality and performance of 
compressing texture images 


Returns: None. 

gllsEnabled 

Purpose: Tests an OpenGL state variable to see whether it is enabled. 
Syntax: 


void glIsEnabled(GLenum feature) ; 


Description: Many OpenGL state variables can be turned on and off with glEnable or 
glDisable. This function allows you to query a given state variable to see 
whether it is currently enabled. Table 2.5 shows the list of states that can 


be queried. 
Returns: None. 
See Also: glEnable, glDisable 
glOrtho 
Purpose: Sets or modifies the clipping volume extents. 
Syntax: 


void glOrtho(GLdouble left, GLdouble right, GLdouble bottom, GLdouble top, GLdouble 
near, GLdouble far); 


Description: This function describes a parallel clipping volume. This projection means 
that objects far from the viewer do not appear smaller (in contrast to a 
perspective projection). Think of the clipping volume in terms of 3D 
Cartesian coordinates, in which case left and right are the minimum 
and maximum x values, top and bottom are the minimum and maximum 
y values, and near and far are the minimum and maximum z values. 


Parameters: 

left GLdouble: The leftmost coordinate of the clipping volume. 
right GLdouble: The rightmost coordinate of the clipping volume. 
bottom GLdouble: The bottommost coordinate of the clipping volume. 
top GLdouble: The topmost coordinate of the clipping volume. 

near GLdouble: The maximum distance from the origin to the viewer. 


far GLdouble: The maximum distance from the origin away from the viewer. 
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Returns: None. 


See Also: glViewport 


glPushAttrib/glPopAttrib 


Save and restore a set of related OpenGL state values. 


Purpose: 
Syntax: 
void glPushAttrib(GLbitfield mask) ; 
void glPopAttrib(GLbitfield mask) ; 


Description: OpenGL allows for whole groups of state variables to be saved and 
retrieved. These functions push these groups onto an attribute stack and 
allow for them to be popped back off the stack. Table 2.6 shows the 
complete list of attribute groups. 


Returns: None. 


TABLE 2.6 OpenGL Attribute Groups 
Attributes 


Constant 


GL_ACCUM_BUFFER_BIT 
GL_COLOR_BUFFER_BIT 
GL_CURRENT_BIT 

GL_DEPTH_BUFFER_BIT 


Accumulation buffer settings 
Color buffer settings 

Current color and coordinates 
Depth buffer settings 


GL_ENABLE_BIT 
GL_EVAL_BIT 
GL_FOG_BIT 
GL_HINT_BIT 
GL_LIGHTING_BIT 
GL_LINE_BIT 
GL_LIST_BIT 
GL_MULTISAMPLE_BIT 
GL_PIXEL_MODE_BIT 
GL_POINT_BIT 
GL_POLYGON_BIT 


GL_POLYGON_STIPPLE_BIT 


GL_SCISSOR_BIT 
GL_STENCIL_BUFFER_BIT 
GL_TEXTURE_BIT 
GL_TRANSFORM_BIT 
GL_VIEWPORT_BIT 
GL_ALL_ATTRIB_BITS 


All enabled flags 
Evaluator settings 

Fog settings 

All OpenGL hints 
Lighting Settings 

Line settings 

Display list settings 
Multisampling 

Pixel mode 

Point settings 

Polygon mode settings 
Polygon stipple settings 
Scissor test settings 
Stencil buffer settings 
Texture settings 
Transformation settings 
Viewport settings 

All OpenGL states 


glRect 


Purpose: 
Variations: 


Reference 


Draws a flat rectangle. 


void glRectd(GLdouble x7, GLdouble y7, GLdouble x2, GLdouble y2); 
void glRectf(GLfloat x7, GLfloat y7, GLfloat x2, GLfloat y2); 
void glRecti(GLint x7, GLint y7, GLint x2, GLint y2); 

void glRects(GLshort x7, GLshort y7, GLshort x7, GLshort y2); 
void glRectdv(const GLdouble *v7, const GLdouble *v2); 

void glRectfv(const GLfloat *v7, const GLfloat *v2); 

void glRectiv(const GLint *v7, const GLint *v2); 

void glRectsv(const GLshort *v7, const GLshort *v2); 


Description: 


Parameters: 
x1, yl 
X2, ye 


*v1 
=e: 
Returns: 


glViewport 
Purpose: 
Syntax: 


This function provides a simple method of specifying a rectangle as two 
corner points. The rectangle is drawn in the xy plane at z = 0. 


Specifies the upper-left corner of the rectangle. 
Specifies the lower-right corner of the rectangle. 


An array of two values specifying the upper-left corner of the rectangle. 
Could also be described as v1[2]. 


An array of two values specifying the lower-right corner of the rectangle. 
Could also be described as v2[2]. 


None. 


Sets the portion of a window that can be drawn in by OpenGL. 


void glViewport(GLint x, GLint y, GLsizei width, GLsizei height); 


Description: 


Parameters: 


x 


This function sets the region within a window that is used for mapping 
the clipping volume coordinates to physical window coordinates. 


GLint: The number of pixels from the left side of the window to start the 
viewport. 
GLint: The number of pixels from the bottom of the window to start the 
viewport. 
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width GLsizei: The width in pixels of the viewport. 

height GLsizei: The height in pixels of the viewport. 

Returns: None. 

See Also: gl0rtho 

gluErrorString 

Purpose: Returns a character string explanation for an OpenGL error code. 
Syntax: 


const GLubyte* gluErrorString(GLenum errCode) ; 


Description: This function returns an error string, given an error code returned by the 
glGetError function. 

Parameters: 

errCode An OpenGL error code. 

Returns: A constant pointer to an OpenGL error string. 

See Also: glGetError 

glutCreateWindow 

Purpose: Creates an OpenGL-enabled window. 

Syntax: 


int glutCreateWindow(char *name) ; 


Description: This function creates a top-level window in GLUT. This is considered the 
current window. 

Parameters: 

name char *: The caption the window is to bear. 

Returns: An integer uniquely identifying the window created. 

See Also: glutInitDisplayMode 

glutDisplayFunc 

Purpose: Sets the display callback function for the current window. 

Syntax: 


void glutDisplayFunc(void (*func) (void) ; 


Reference 


Description: This function tells GLUT which function to call whenever the windows 
contents must be drawn. This can occur when the window is resized or 
uncovered or when GLUT is specifically asked to refresh with a call to the 
glutPostRedisplay function. Note that GLUT does not explicitly call 
glFlush or glutSwapBuffers for you after this function is called. 


Parameters: 

func (*func) (void): The name of the function that does the rendering. 
Returns: None. 

See Also: glFlush, glutSwapBuffers, glutReshapeFunc 


glutinitDisplayMode 


Purpose: Initializes the display mode of the GLUT library OpenGL window. 
Syntax: 
void glutInitDisplayMode(unsigned int mode); 


Description: This is the first function that must be called by a GLUT-based program to 
set up the OpenGL window. This function sets the characteristics of the 
window that OpenGL will use for drawing operations. 


Parameters: 

mode unsigned int: A mask or bitwise combination of masks from Table 2.7. 
These mask values may be combined with a bitwise OR. 

Returns: None. 

See Also: glutCreateWindow 


TABLE 2.7. Mask Values for Window Characteristics 


Mask Value Meaning 

GLUT_SINGLE Specifies a single-buffered window 
GLUT_DOUBLE Specifies a double-buffered window 
GLUT_RGBA or GLUT_RGB Specifies an RGBA-mode window 
GLUT_DEPTH Specifies a 32-bit depth buffer 
GLUT_LUMINANCE Specifies a luminance only color buffer 
GLUT_MULTISAMPLE Specifies a multisampled color buffer 
GLUT_STENCIL Specifies a stencil buffer 

GLUT_STEREO Specifies a stereo color buffer 
GLUT_ACCUM Specifies an accumulation buffer 


GLUT_ALPHA Specifies a destination alpha buffer 
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glutKeyboardFunc 
Purpose: Sets the keyboard callback function for the current window. 
Syntax: 


void glutKeyboardFunc(void (*func) (unsigned char key, int x, int y); 


Description: This function establishes a callback function called by GLUT whenever 
one of the ASCII generating keys is pressed. Non-ASCII generating keys 
such as the Shift key are handled by the glutSpecialFunc callback. In 
addition to the ASCII value of the keystroke, the current x and y position 
of the mouse are returned. 


Parameters: 

func (*func) (unsigned char key, int x, int y): The name of the function 
to be called by GLUT when a keystroke occurs. 

Returns: None. 

glutMainLoop 

Purpose: Starts the main GLUT processing loop. 

Syntax: 


void glutMainLoop(void) ; 


Description: This function begins the main GLUT event-handling loop. The event 
loop is the place where all keyboard, mouse, timer, redraw, and other 
window messages are handled. This function does not return until 
program termination. 


Parameters: None. 

Returns: None. 

glutMouseFunc 

Purpose: Sets the mouse callback function for the current window. 
Syntax: 


void glutMouseFunc(void (*func)(int button, int state, int x, int y); 


Description: This function establishes a callback function called by GLUT whenever a 
mouse event occurs. Three values are valid for the button parameter: 
GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, and GLUT_RIGHT_BUTTON. The 
state parameter is either GLUT_UP or GLUT_DOWN. 


Reference 85 


Parameters: 
func (*func)(int button, int state, int x, int y): The name of the 

function to be called by GLUT when a mouse event occurs. 
Returns: None. 
See Also: glutSpecialFunc, glutKeyboardFunc 

~) 

glutReshapeFunc 
Purpose: Sets the window reshape callback function for the current window. 
Syntax: 


void glutReshapeFunc(void (*func)(int width, int height); 


Description: This function establishes a callback function called by GLUT whenever 
the window changes size or shape (including at least once when the 
window is created). The callback function receives the new width and 
height of the window. 


Parameters: 

func (*func) (int x, int y): The name of the function to be called by GLUT 
when the window size changes. 

Returns: None. 

See Also: glutDisplayFunc 

glutPostRedisplay 

Purpose: Tells GLUT to refresh the current window. 

Syntax: 


void glutPostRedisplay (void) ; 


Description: This function informs the GLUT library that the current window needs to 
be refreshed. Multiple calls to this function before the next refresh result 
in only one repainting of the window. 


Parameters: None. 
Returns: None. 
See Also: glutDisplayFunc 
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glutSolidTeapot, glutWireTeapot 


Purpose: Draws a solid or wireframe teapot. 
Syntax: 


void glutSolidTeapot(GLdouble size); 
void glutWireTeapot(GLdouble size); 


Description: This function draws a solid or wireframe teapot. This is the famous teapot 
seen so widely in computer graphics samples. In addition to surface 
normals for lighting, texture coordinates are also generated. 


Parameters: 

size GLdouble: The approximate radius of the teapot. A sphere of this radius 
would totally enclose the model. 

Returns: None. 

glutSpecialFunc 

Purpose: Sets a special keyboard callback function for the current window for non- 
ASCII keystrokes. 

Syntax: 


void glutSpecialFunc(void (*func)(int key, int x, int y); 


Description: This function establishes a callback function called by GLUT whenever 
one of the non-ASCII generating keys is pressed. Non-ASCII generating 
keys are keystrokes such as the Shift key, which can’t be identified by an 
ASCII value. In addition, the current x and y position of the mouse are 
returned. Valid values for the key parameter are listed in Table 2.8. 


Parameters: 

func (*func) (int key, int x, int y): The name of the function to be 
called by GLUT when a non-ASCII keystroke occurs. 

Returns: None. 

See Also: glutKeyboardFunc, glutMouseFunc 


TABLE 2.8 Non-ASCll Key Values Passed to the glutSpecialFunc Callback 
Key Value Keystroke 


GLUT_KEY_F1 F1 key 
GLUT_KEY_F2 F2 key 
GLUT_KEY_F3 F3 key 
GLUT_KEY_F4 F4 key 


GLUT_KEY_F5 FS key 
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Key Value Keystroke 
GLUT_KEY_F6 F6 key 
GLUT_KEY_F7 F7 key 
GLUT_KEY_F8 F8 key 
GLUT_KEY_F9 F9 key 
GLUT_KEY_F10 F10 key 
GLUT_KEY_F11 F11 key N 
GLUT_KEY_F12 F12 key 
GLUT_KEY_LEFT Left-arrow key 
GLUT_KEY_RIGHT Right-arrow key 
GLUT_KEY_UP Up-arrow key 
GLUT_KEY_DOWN Down-arrow key 
GLUT_KEY_PAGE_UP Page Up key 
GLUT_KEY_PAGE_DOWN Page Down key 
GLUT_KEY_HOME Home key 
GLUT_KEY_END End key 
GLUT_KEY_INSERT Insert key 
glutSwapBuffers 
Purpose: Performs a buffer swap in double-buffered mode. 
Syntax: 


void glutSwapBuffers (void) ; 


Description: When the current GLUT window is operating in double-buffered mode, 
this function performs a flush of the OpenGL pipeline and does a buffer 
swap (places the hidden rendered image onscreen). If the current window 
is not in double-buffered mode, a flush of the pipeline is still performed. 


Parameters: None. 

Returns: None. 

See Also: glutDisplayFunc 

glutTimerFunc 

Purpose: Registers a callback function to be called by GLUT after the timeout value 
expires. 

Syntax: 


void glutTimerFunc(unsigned int msecs, (*func)(int value),int value); 
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Description: 


Parameters: 


msecs 


func 


value 


Returns: 


This function registers a callback function that should be called after 
msecs milliseconds have elapsed. The callback function is passed the user- 
specified value in the value parameter. 


unsigned int: The number of milliseconds to wait before calling the 
specified function. 


void (*func)(int value): The name of the function to be called when 
the timeout value expires. 


int: User-specified value passed to the callback function when it is 
executed. 


None. 


CHAPTER 3 


Drawing in Space: Geometric 
Primitives and Buffers 


by Richard S. Wright, Jr. 


WHAT YOU’LL LEARN IN THIS CHAPTER: 


How To Functions You'll Use 
Draw points, lines, and shapes glBegin/glEnd/glvertex 
Set shape outlines to wireframe glPolygonMode 

or solid objects 

Set point sizes for drawing glPointSize 

Set line drawing width glLineWidth 

Perform hidden surface removal glCullFace/glClear 

Set patterns for broken lines glLineStipple 

Set polygon fill patterns glPolygonStipple 

Use the OpenGL Scissor box glScissor 

Use the stencil buffer glStencilFunc/glStencilMask/glStencil0p 


If you’ve ever had a chemistry class (and probably even if you haven’t), you know that all 
matter consists of atoms and that all atoms consist of only three things: protons, 
neutrons, and electrons. All the materials and substances you have ever come into contact 
with—from the petals of a rose to the sand on the beach—are just different arrangements 
of these three fundamental building blocks. Although this explanation is a little oversim- 
plified for almost anyone beyond the third or fourth grade, it demonstrates a powerful 
principle: With just a few simple building blocks, you can create highly complex and 
beautiful structures. 


The connection is fairly obvious. Objects and scenes that you create with OpenGL also 
consist of smaller, simpler shapes, arranged and combined in various and unique ways. 
This chapter explores these building blocks of 3D objects, called primitives. All primitives 
in OpenGL are one- or two-dimensional objects, ranging from single points to lines and 
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complex polygons. In this chapter, you learn everything you need to know to draw objects 
in three dimensions from these simpler shapes. 


Drawing Points in 3D 


When you first learned to draw any kind of graphics on any computer system, you proba- 
bly started with pixels. A pixel is the smallest element on your computer monitor, and on 
color systems, that pixel can be any one of many available colors. This is computer graph- 
ics at its simplest: Draw a point somewhere on the screen, and make it a specific color. 
Then build on this simple concept, using your favorite computer language to produce 
lines, polygons, circles, and other shapes and graphics. Perhaps even a GUI... 


With OpenGL, however, drawing on the computer screen is fundamentally different. 
You’re not concerned with physical screen coordinates and pixels, but rather positional 
coordinates in your viewing volume. You let OpenGL worry about how to get your points, 
lines, and everything else projected from your established 3D space to the 2D image made 
by your computer screen. 


This chapter and the next cover the most fundamental concepts of OpenGL or any 3D 
graphics toolkit. In the upcoming chapter, we provide substantial detail about how this 
transformation from 3D space to the 2D landscape of your computer monitor takes place, 
as well as how to transform (rotate, translate, and scale) your objects. For now, we take 
this ability for granted to focus on plotting and drawing in a 3D coordinate system. This 
approach might seem backward, but if you first know how to draw something and then 
worry about all the ways to manipulate your drawings, the material in Chapter 4, 
“Geometric Transformations: The Pipeline,” is more interesting and easier to learn. When 
you have a solid understanding of graphics primitives and coordinate transformations, 
you will be able to quickly master any 3D graphics language or API. 


Setting Up a 3D Canvas 


Figure 3.1 shows a simple viewing volume that we use for the examples in this chapter. 
The area enclosed by this volume is a Cartesian coordinate space that ranges from —100 to 
+100 on all three axes—x, y, and z. (For a review of Cartesian coordinates, see Chapter 1, 
“Introduction to 3D Graphics and OpenGL.”) Think of this viewing volume as your three- 
dimensional canvas on which you draw with OpenGL commands and functions. 


We established this volume with a call to gl0rtho, much as we did for others in the 
preceding chapter. Listing 3.1 shows the code for the ChangeSize function that is called 
when the window is sized (including when it is first created). This code looks a little differ- 
ent from that in preceding chapter, and you’ll notice some unfamiliar functions 
(glMatrixMode, glLoadIdentity). We spend more time on these functions in Chapter 4, 
exploring their operation in more detail. 


Setting Up a 3D Canvas 


FIGURE 3.1 Cartesian viewing volume measuring 100x100x100. 


LISTING 3.1 Code to Establish the Viewing Volume in Figure 3.1 


// Change viewing volume and viewport. Called when window is resized 
void ChangeSize(GLsizei w, GLsizei h) 


{ 
GLfloat nRange = 100.0f; 


// Prevent a divide by zero 
if ( == Q) 
h= 1; 


// Set Viewport to window dimensions 
glViewport(@, ®, w, h); 


// Reset projection matrix stack 
glMatrixMode(GL_PROJECTION) ; 
glLoadidentity(); 


// Establish clipping volume (left, right, bottom, top, near, far) 
if (w <= h) 
glOrtho (-nRange, nRange, -nRange*h/w, nRange*h/w, -nRange, nRange); 
else 
gl0rtho (-nRange*w/h, nRange*w/h, -nRange, nRange, -nRange, nRange) ; 


// Reset Model view matrix stack 
glMatrixMode (GL_MODELVIEW) ; 
glLoadidentity(); 

} 
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WHY THE CART BEFORE THE HORSE? 


Look at any of the source code in this chapter, and you'll notice some new functions in the 
RenderScene functions: glRotate, glPushMatrix, and glPopMatrix. Although they’re covered in 
more detail in Chapter 4, we’re introducing them now. They implement some important features 
that we want you to have as soon as possible. These functions let you plot and draw in 3D and 
help you easily visualize your drawing from different angles. All this chapter’s sample programs 
employ the arrow keys for rotating the drawing around the x- and y-axes. Look at any 3D 
drawing dead-on (straight down the z-axis), and it might still look two-dimensional. But when 
you can spin the drawings around in space, it’s much easier to see the 3D effects of what you're 
drawing. 

There is a lot to learn about drawing in 3D, and in this chapter, we want you to focus on that. By 
changing only the drawing code for any of the examples that follow, you can start experimenting 
right away with 3D drawing and still get interesting results. Later, you'll learn how to manipulate 
drawings using the other functions. 


A 3D Point: The Vertex 


To specify a drawing point in this 3D “palette,” we use the OpenGL function glVertex— 
without a doubt the most used function in all the OpenGL API. This is the “lowest 
common denominator” of all the OpenGL primitives: a single point in space. The 
glVertex function can take from one to four parameters of any numerical type, from bytes 
to doubles, subject to the naming conventions discussed in Chapter 2, “Using OpenGL.” 


The following single line of code specifies a point in our coordinate system located 50 
units along the x-axis, 50 units along the y-axis, and 0 units out the z-axis: 


glVertex3f (50.0f, 50.0f, 0.0f); 
Figure 3.2 illustrates this point. Here, we chose to represent the coordinates as floating- 


point values, as we do for the remainder of the book. Also, the form of glVertex that we 
use takes three arguments for the x, y, and z coordinate values, respectively. 


FIGURE 3.2 The point (50,50,0) as specified by gl1Vertex3f(50.0f, 50.0f, 0.0f). 
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Two other forms of glVertex take two and four arguments, respectively. We can represent 
the same point in Figure 3.2 with this code: 


glVertex2f(50.0f, 50.0f); 


This form of glVertex takes only two arguments that specify the x and y values and 
assumes the z coordinate to be 0.0 always. 


The form of glVertex taking four arguments, glVertex4, uses a fourth coordinate value w 

(set to 1.0 by default when not specified) for scaling purposes. You will learn more about 

this coordinate in Chapter 4 when we spend more time exploring coordinate transforma- 

tions. Ww 


Draw Something! 


Now, we have a way of specifying a point in space to OpenGL. What can we make of it, 
and how do we tell OpenGL what to do with it? Is this vertex a point that should just be 
plotted? Is it the endpoint of a line or the corner of a cube? The geometric definition of a 
vertex is not just a point in space, but rather the point at which an intersection of two 
lines or curves occurs. This is the essence of primitives. 


A primitive is simply the interpretation of a set or list of vertices into some shape drawn 
on the screen. There are 10 primitives in OpenGL, from a simple point drawn in space to a 
closed polygon of any number of sides. One way to draw primitives is to use the glBegin 
command to tell OpenGL to begin interpreting a list of vertices as a particular primitive. 
You then end the list of vertices for that primitive with the glEnd command. Kind of intu- 
itive, don’t you think? 


Drawing Points 
Let’s begin with the first and simplest of primitives: points. Look at the following code: 


glBegin(GL_POINTS) ; // Select points as the primitive 
glVertex3f(0.0f, 0.0f, 0.0f); // Specify a point 
glVertex3f (50.0f, 50.0f, 50.0f); // Specify another point 
glEnd(); // Done drawing points 


The argument to g1Begin, GL_POINTS, tells OpenGL that the following vertices are to be 
interpreted and drawn as points. Two vertices are listed here, which translates to two 
specific points, both of which would be drawn. 


This example brings up an important point about g1Begin and glEnd: You can list multi- 
ple primitives between calls as long as they are for the same primitive type. In this way, 
with a single g1Begin/glEnd sequence, you can include as many primitives as you like. 
This next code segment is wasteful and will execute more slowly than the preceding code: 
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glBegin(GL_POINTS) ; // Specify point drawing 
glVertex3f(0.0f, @.0f, 0.0f); 

glEnd(); 

glBegin(GL_POINTS) ; // Specify another point 
glVertex3f(50.0f, 50.0f, 50.0f); 

glEnd() 


INDENTING YOUR CODE 


In the foregoing examples, did you notice the indenting style used for the calls to glVertex? 
Most OpenGL programmers use this convention to make the code easier to read. It is not 
required, but it does make finding where primitives start and stop easier. 


Our First Example 

The code in Listing 3.2 draws some points in our 3D environment. It uses some simple 
trigonometry to draw a series of points that form a corkscrew path up the z-axis. This code 
is from the POINTS program, which is on the CD in the subdirectory for this chapter. All 
the sample programs use the framework we established in Chapter 2. Notice that in the 
SetupRC function, we are setting the current drawing color to green. 


LISTING 3.2 Rendering Code to Produce a Spring-Shaped Path of Points 


// Define a constant for the value of PI 
#define GL_PI 3.1415f 


// This function does any needed initialization on the rendering 
// context. 
void SetupRC() 

{ 

// Black background 

glClearColor(@.0f, 0.0f, 0.0f, 1.0f ); 


// Set drawing color to green 
glColor3f(0.0f, 1.0f, 0.0f); 
} 


// Called to draw scene 
void RenderScene (void) 


{ 
GLfloat x,y,z,angle; // Storage for coordinates and angles 
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LISTING 3.2 Continued 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Save matrix state and do the rotation 
glPushMatrix(); 

glRotatef(xRot, 1.0f, 0.0f, 0.0f); 
glRotatef(yRot, 0.0f, 1.0f, 0.0f); 


// Call only once for all remaining points 
glBegin(GL_POINTS) ; 


z = -50.0f; 

for(angle = 0.0f; angle <= (2.0f*GL_PI)*3.0f; angle += 0.1f) 
{ 
x = 50.0f*sin(angle) ; 


y = 50.0f*cos(angle); 

// Specify the point and move the Z value up a little 
glVertex3f(x, y, Z); 

z += 0.5f; 

} 


// Done drawing points 
glEnd(); 


// Restore transformations 
glPopMatrix(); 


// Flush drawing commands 
glFlush(); 
} 


Only the code between calls to g1Begin and glEnd is important for our purpose in this and 
the other examples for this chapter. This code calculates the x and y coordinates for an 
angle that spins between 0° and 360° three times. We express this programmatically in 
radians rather than degrees; if you don’t know trigonometry, you can take our word for it. 
If you’re interested, see the box “The Trigonometry of Radians/Degrees.” Each time a point 
is drawn, the z value is increased slightly. When this program is run, all you see is a circle 
of points because you are initially looking directly down the z-axis. To see the effect, use 
the arrow keys to spin the drawing around the x- and y-axes. The effect is illustrated in 
Figure 3.3. 
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Pomts Example 


FIGURE 3.3 Output from the POINTS sample program. 


ONE THING AT A TIME 


Again, don’t get too distracted by the functions in this example that we haven’t covered yet 
(glPushMatrix, glPopMatrix, and glRotate). These functions are used to rotate the image 
around so you can better see the positioning of the points as they are drawn in 3D space. We 
cover these functions in some detail in Chapter 4. If we hadn’t used these features now, you 
wouldn’t be able to see the effects of your 3D drawings, and this and the following sample 
programs wouldn’t be very interesting to look at. For the rest of the sample code in this chapter, 
we show only the code that includes the glBegin and glEnd statements. 


x = cos(a) 
y = sin(a) 
22°17 *5, 40 


THE TRIGONOMETRY OF RADIANS/DEGREES 


The figure in this box shows a circle drawn in the xy plane. A line segment from the origin (0,0) 
to any point on the circle makes an angle (a) with the x-axis. For any given angle, the trigono- 

metric functions sine and cosine return the x and y values of the point on the circle. By stepping 
a variable that represents the angle all the way around the origin, we can calculate all the points 


Setting the Point Size 


on the circle. Note that the C runtime functions sin() and cos() accept angle values measured 
in radians instead of degrees. There are 2*PI radians in a circle, where PI is a nonrational number 
that is approximately 3.1415. (Nonrational means there are an infinite number of values past the 
decimal point.) 


Setting the Point Size 


When you draw a single point, the size of the point is one pixel by default. You can 
change this size with the function g1PointSize: 


void glPointSize(GLfloat size); 


The glPointSize function takes a single parameter that specifies the approximate diameter 
in pixels of the point drawn. Not all point sizes are supported, however, and you should 
make sure the point size you specify is available. Use the following code to get the range 
of point sizes and the smallest interval between them: 


GLfloat sizes[2]; // Store supported point size range 
GLfloat step; // Store supported point size increments 


// Get supported point size range and step size 
glGetFloatv(GL_POINT_SIZE_RANGE, sizes) ; 
glGetFloatv(GL_POINT_SIZE_GRANULARITY, &step) ; 


Here, the sizes array will contain two elements that contain the smallest and largest valid 
value for glPointsize. In addition, the variable step will hold the smallest step size allow- 
able between the point sizes. The OpenGL specification requires only that one point size, 
1.0, be supported. The Microsoft software implementation of OpenGL, for example, allows 
for point sizes from 0.5 to 10.0, with 0.125 the smallest step size. Specifying a size out of 
range is not interpreted as an error. Instead, the largest or smallest supported size is used, 
whichever is closest to the value specified. 


Points, unlike other geometry, are not affected by the perspective division. That is, they do 
not become smaller when they are further from the viewpoint, and they do not become 
larger as they move closer. Points are also always square pixels, even if you use 
g1PointSize to increase the size of the points. You just get bigger squares! To get round 
points, you must draw them antialiased (coming up in the next chapter). 


OPENGL STATE VARIABLES 


As we discussed in Chapter 2, OpenGL maintains the state of many of its internal variables and 
settings. This collection of settings is called the OpenGL State Machine. You can query the State 
Machine to determine the state of any of its variables and settings. Any feature or capability you 
enable or disable with glEnable/g1Disable, as well as numeric settings set with glSet, can be 
queried with the many variations of glGet. 
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Let’s look at a sample that uses these new functions. The code in Listing 3.3 produces the 
same spiral shape as our first example, but this time, the point sizes are gradually 
increased from the smallest valid size to the largest valid size. This example is from the 
program POINTSZ in the CD subdirectory for this chapter. The output from POINTSZ 
shown in Figure 3.4 was run on Microsoft's software implementation of OpenGL. Figure 
3.5 shows the same program run on a hardware accelerator that supports much larger 
point sizes. 


Points Size Example 


FIGURE 3.4 Output from the POINTSZ program. 


“> 


FIGURE 3.5 Output from POINTSZ on hardware supporting much larger point sizes. 


LISTING 3.3 Code from POINTSZ That Produces a Spiral with Gradually Increasing Point 
Sizes 


// Define a constant for the value of PI 
#define GL_PI 3.1415f 
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LISTING 3.3 Continued 


// Called to draw scene 
void RenderScene(void) 


{ 

GLfloat x,y,z,angle; // Storage for coordinates and angles 
GLfloat sizes[2]; // Store supported point size range 
GLfloat step; // Store supported point size increments 


GLfloat curSize; // Store current point size 


// Get supported point size range and step size 
glGetFloatv(GL_POINT_SIZE_RANGE, sizes) ; 
glGetFloatv(GL_POINT_SIZE_GRANULARITY, &step) ; 


// Set the initial point size 
curSize = sizes[]; 


// Set beginning z coordinate 
z = -50.0f; 


// Loop around in a circle three times 
for(angle = 0.0f; angle <= (2.0f*GL_PI)*3.0f; angle += 0.1f) 
{ 
// Calculate x and y values on the circle 
xX = 50.0f*sin(angle) ; 
y = 50.0f*cos(angle) ; 


// Specify the point size before the primitive is specified 
glPointSize(curSize) ; 


// Draw the point 
glBegin(GL_POINTS) ; 

glVertex3f(x, y, 2); 
glEnd(); 


// Bump up the z value and the point size 
z += 0.5f; 
curSize += step; 


} 
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This example demonstrates a couple of important things. For starters, notice that 
glPointSize must be called outside the g1Begin/glEnd statements. Not all OpenGL func- 
tions are valid between these function calls. Although glPointSize affects all points 
drawn after it, you don’t begin drawing points until you call glBegin(GL_POINTS). For a 
complete list of valid functions that you can call within a g1Begin/glEnd sequence, see the 
reference section at the end of the chapter. 


If you specify a point size larger than what is returned in the size variable, you also may 
notice (depending on your hardware) that OpenGL uses the largest available point size but 
does not keep growing. This is a general observation about OpenGL function parameters 
that have a valid range. Values outside the range are clamped to the range. Values too low 
are made the lowest valid value, and values too high are made the highest valid value. 


The most obvious thing you probably noticed about the POINTSZ excerpt is that the larger 
point sizes are represented simply by larger cubes. This is the default behavior, but it typi- 
cally is undesirable for many applications. Also, you might wonder why you can increase 
the point size by a value less than one. If a value of 1.0 represents one pixel, how do you 
draw less than a pixel or, say, 2.5 pixels? 


The answer is that the point size specified in glPointSize isn’t the exact point size in 
pixels, but the approximate diameter of a circle containing all the pixels that are used to 
draw the point. You can get OpenGL to draw the points as better points (that is, small 
filled circles) by enabling point smoothing. Together with line smoothing, point smooth- 
ing falls under the topic of antialiasing. Antialiasing is a technique used to smooth out 
jagged edges and round out corners; it is covered in more detail in Chapter 6, “More on 
Colors and Materials.” 


Drawing Lines in 3D 


The GL_POINTS primitive we have been using thus far is reasonably straightforward; for 
each vertex specified, it draws a point. The next logical step is to specify two vertices and 
draw a line between them. This is exactly what the next primitive, G__LINES, does. The 
following short section of code draws a single line between two points (0,0,0) and 
(S0,50,50): 


glBegin(GL_LINES) ; 
glVertex3f(0.0f, 0.0f, 0.0f); 
glVertex3f(50.0f, 50.0f, 50.0f); 
glEnd(); 


Note here that two vertices specify a single primitive. For every two vertices specified, a 
single line is drawn. If you specify an odd number of vertices for GL_LINES, the last vertex 
is just ignored. Listing 3.4, from the LINES sample program on the CD, shows a more 
complex sample that draws a series of lines fanned around in a circle. Each point specified 
in this sample is paired with a point on the opposite side of a circle. The output from this 
program is shown in Figure 3.6. 
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FIGURE 3.6 Output from the LINES sample program. 


LISTING 3.4 Code from the Sample Program LINES That Displays a Series of Lines Fanned in 
a Circle 


// Call only once for all remaining points 
glBegin(GL_LINES) ; 


// All lines lie in the xy plane. 


Zz = 0.0Ff; 
for(angle = 0.0f; angle <= GL_PI; angle += (GL_PI/20.0f)) 
{ 


// Top half of the circle 

x = 50.0f*sin(angle) ; 

y = 50.0f*cos(angle) ; 

glVertex3f(x, y, Z); // First endpoint of line 


// Bottom half of the circle 

xX = 50.0f*sin(angle + GL_PI); 

y = 50.0f*cos(angle + GL_PI); 

glVertex3f(x, y, Z); // Second endpoint of line 
} 
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LISTING 3.4 Continued 


// Done drawing points 
glEnd(); 


Line Strips and Loops 

The next two OpenGL primitives build on GL_LINES by allowing you to specify a list of 
vertices through which a line is drawn. When you specify GL_LINE_STRIP, a line is drawn 
from one vertex to the next in a continuous segment. The following code draws two lines 
in the xy plane that are specified by three vertices. Figure 3.7 shows an example. 


glBegin(GL_LINE_STRIP) ; 
glVertex3f(0.0f, 0.0f, 0.0f); // VO 


glVertex3f (50.0f, 50.0f, 0.0f); // v1 
glVertex3f(50.0f, 100.0f, 0.0f); // V2 
glEnd(); 
y 


e ¥(50,100,0) 


¥,(50,50,0) 


Vo(0,0,0) 


FIGURE 3.7 An example of a GL_LINE_STRIP specified by three vertices. 


The last line-based primitive is G__LINE_LOOP. This primitive behaves just like 
GL_LINE_STRIP, but one final line is drawn between the last vertex specified and the first 
one specified. This is an easy way to draw a closed-line figure. Figure 3.8 shows a 
GL_LINE_LOOP drawn using the same vertices as for the GL_LINE_STRIP in Figure 3.7. 


Approximating Curves with Straight Lines 


The POINTS sample program, shown earlier in Figure 3.3, showed you how to plot points 
along a spring-shaped path. You might have been tempted to push the points closer and 
closer together (by setting smaller values for the angle increment) to create a smooth 
spring-shaped curve instead of the broken points that only approximated the shape. This 
perfectly valid operation can move quite slowly for larger and more complex curves with 
thousands of points. 
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FIGURE 3.8 The same vertices from Figure 3.7 used by a GL_LINE_LOOP primitive. 


A better way of approximating a curve is to use GL_LINE_STRIP to play connect-the-dots. 
As the dots move closer together, a smoother curve materializes without your having to 
specify all those points. Listing 3.5 shows the code from Listing 3.2, with GL_POINTS 
replaced by GL_LINE_STRIP. The output from this new program, LSTRIPS, is shown in 
Figure 3.9. As you can see, the approximation of the curve is quite good. You will find this 
handy technique almost ubiquitous among OpenGL programs. 


Line Strips Example 


FIGURE 3.9 Output from the LSTRIPS program approximating a smooth curve. 


LISTING 3.5 Code from the Sample Program LSTRIPS, Demonstrating Line Strips __ 


// Call only once for all remaining points 
glBegin(GL_LINE STRIP); 


z = -50.0f; 

for(angle = @.0f; angle <= (2.@f*GL_PI)*3.0f; angle += 0.1f) 
{ 
x = 50.0f*sin(angle); 
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LISTING 3.5 Continued 
y = 50.0f*cos(angle) ; 


// Specify the point and move the z value up a little 
glVertex3f(x, y, Z); 

z += 0.5f; 

} 


// Done drawing points 
glEnd(); 


Setting the Line Width 


Just as you can set different point sizes, you can also specify various line widths when 
drawing lines by using the glLineWidth function: 


void glLineWidth(GLfloat width); 


The glLineWidth function takes a single parameter that specifies the approximate width, 
in pixels, of the line drawn. Just like point sizes, not all line widths are supported, and you 
should make sure the line width you want to specify is available. Use the following code 
to get the range of line widths and the smallest interval between them: 


GLfloat sizes[2]; // Store supported line width range 
GLfloat step; // Store supported line width increments 


// Get supported line width range and step size 
glGetFloatv(GL_LINE_WIDTH_RANGE, sizes) ; 
glGetFloatv(GL_LINE_WIDTH_GRANULARITY, &step) ; 


Here, the sizes array will contain two elements that contain the smallest and largest valid 
value for glLineWidth. In addition, the variable step will hold the smallest step size allow- 
able between the line widths. The OpenGL specification requires only that one line width, 
1.0, be supported. The Microsoft implementation of OpenGL allows for line widths from 
0.5 to 10.0, with 0.125 the smallest step size. 


Listing 3.6 shows code for a more substantial example of glLineWidth. It’s from the 
program LINESW and draws 10 lines of varying widths. It starts at the bottom of the 
window at -90 on the y-axis and climbs the y-axis 20 units for each new line. Every time 
it draws a new line, it increases the line width by 1. Figure 3.10 shows the output for this 
program. 
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FIGURE 3.10 Demonstration of gl1LineWidth from the LINESW program. 


LISTING 3.6 Drawing Lines of Various Widths 
// Called to draw scene 
void RenderScene(void) 


{ 

GLfloat y; // Storage for varying Y coordinate 
GLfloat fSizes[2]; // Line width range metrics 
GLfloat fCurrSize; // Save current size 


// Get line size metrics and save the smallest value 
glGetFloatv(GL_LINE_WIDTH_RANGE, fSizes) ; 
fCurrSize = fSizes[0]; 


// Step up y axis 20 units at a time 
for(y = -90.0f; y < 90.0f; y += 20.0f) 
{ 
// Set the line width 
glLineWidth(fCurrSize) ; 


// Draw the line 
glBegin(GL_LINES) ; 
glVertex2f(-80.0f, y); 
glVertex2f (80.0f, y); 
glEnd() ; 


// Increase the line width 
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LISTING 3.6 Continued 
fCurrSize += 1.0f; 


} 


we 


Notice that we used glVertex2f this time instead of glVertex3f to specify the coordinates 
for the lines. As mentioned, using this technique is only a convenience because we are 
drawing in the xy plane, with a z value of 0. To see that you are still drawing lines in three 
dimensions, simply use the arrow keys to spin your lines around. You easily see that all 
the lines lie on a single plane. 


Line Stippling 
In addition to changing line widths, you can create lines with a dotted or dashed pattern, 
called stippling. To use line stippling, you must first enable stippling with a call to 


glEnable(GL_LINE_STIPPLE) ; 


Then the function glLineStipple establishes the pattern that the lines use for drawing: 


void glLineStipple(GLint factor, GLushort pattern) ; 


REMINDER 


Any feature or ability that is enabled by a call to glEnable can be disabled by a call to 
glDisable. 


The pattern parameter is a 16-bit value that specifies a pattern to use when drawing the 
lines. Each bit represents a section of the line segment that is either on or off. By default, 
each bit corresponds to a single pixel, but the factor parameter serves as a multiplier to 

increase the width of the pattern. For example, setting factor to 5 causes each bit in the 
pattern to represent five pixels in a row that are either on or off. Furthermore, bit 0 (the 

least significant bit) of the pattern is used first to specify the line. Figure 3.11 illustrates a 
sample bit pattern applied to a line segment. 


WHY ARE THESE PATTERNS BACKWARD? 


You might wonder why the bit pattern for stippling is used in reverse when drawing the line. 
Internally, it’s much faster for OpenGL to shift this pattern to the left one place each time it needs 
to get the next mask value. OpenGL was designed for high-performance graphics and frequently 
employs similar tricks elsewhere. 
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FIGURE 3.11 A stipple pattern is used to construct a line segment. 


Listing 3.7 shows a sample of using a stippling pattern that is just a series of alternating on 
and off bits (0101010101010101). This code is taken from the LSTIPPLE program, which 
draws 10 lines from the bottom of the window up the y-axis to the top. Each line is stip- 
pled with the pattern 0x5555, but for each new line, the pattern multiplier is increased by 
1. You can clearly see the effects of the widened stipple pattern in Figure 3.12. 


Stippled Line Example 


FIGURE 3.12 Output from the LSTIPPLE program. 


LISTING 3.7 Code from LSTIPPLE That Demonstrates the Effect of factor on the Bit Pattern 


// Called to draw scene 
void RenderScene( void) 


{ 
GLfloat y; // Storage for varying y coordinate 
GLint factor = 1; // Stippling factor 


GLushort pattern = 0x5555; // Stipple pattern 
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LISTING 3.7 Continued 


// Enable Stippling 
glEnable(GL_LINE_STIPPLE) ; 


// Step up Y axis 20 units at a time 

for(y = -90.0f; y < 90.0f; y += 20.0f) 
{ 
// Reset the repeat factor and pattern 
glLineStipple(factor, pattern) ; 


// Draw the line 
glBegin(GL_LINES) ; 
glVertex2f(-80.0f, y); 
glVertex2f(80.0f, y); 
glEnd(); 


factort+t+; 


} 


Just the ability to draw points and lines in 3D gives you a significant set of tools for creat- 
ing your own 3D masterpiece. | wrote the commercial application shown in Figure 3.13. 
Note that the OpenGL-rendered map is rendered entirely of solid and stippled line strips. 


FIGURE 3.13. A 3D map rendered with solid and stippled lines. 
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Drawing Triangles in 3D 


You've seen how to draw points and lines and even how to draw some enclosed polygons 
with GL_LINE_LOOP. With just these primitives, you could easily draw any shape possible 
in three dimensions. You could, for example, draw six squares and arrange them so they 
form the sides of a cube. 


You might have noticed, however, that any shapes you create with these primitives are not 
filled with any color; after all, you are drawing only lines. In fact, all that arranging six 
squares produces is a wireframe cube, not a solid cube. To draw a solid surface, you need 
more than just points and lines; you need polygons. A polygon is a closed shape that may 
or may not be filled with the currently selected color, and it is the basis of all solid-object 
composition in OpenGL. 


Triangles: Your First Polygon 


The simplest polygon possible is the triangle, with only three sides. The GL_TRIANGLES 
primitive draws triangles by connecting three vertices together. The following code draws 
two triangles using three vertices each, as shown in Figure 3.14: 


glBegin(GL_TRIANGLES) ; 


glVertex2f(@.0f, 0.0f); // VO 

glVertex2f(25.0f, 25.0f); // M1 

glVertex2f(50.0f, 0.0f); // V2 

glVertex2f(-50.0f, 0.0f); // V3 

glVertex2f(-75.0f, 50.0f); /] V4 

glVertex2f(-25.0f, 0.0f); // V5 
glEnd() ; 


FIGURE 3.14 Two triangles drawn using GL_TRIANGLES. 
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The triangles will be filled with the currently selected drawing color. If you don’t specify a 
drawing color at some point, you can’t be certain of the result. 


Winding 

An important characteristic of any polygonal primitive is illustrated in Figure 3.14. Notice 
the arrows on the lines that connect the vertices. When the first triangle is drawn, the 
lines are drawn from VO to V1, then to V2, and finally back to VO to close the triangle. 
This path is in the order that the vertices are specified, and for this example, that order is 
clockwise from your point of view. The same directional characteristic is present for the 
second triangle as well. 


The combination of order and direction in which the vertices are specified is called 
winding. The triangles in Figure 3.14 are said to have clockwise winding because they are 
literally wound in the clockwise direction. If we reverse the positions of V4 and V5 on the 
triangle on the left, we get counterclockwise winding. Figure 3.15 shows two triangles, each 
with opposite windings. 


Counterclockwise Clockwise winding 
winding (Front facing) (Back facing) 


FIGURE 3.15 Two triangles with different windings. 


OpenGL, by default, considers polygons that have counterclockwise winding to be front 
facing. This means that the triangle on the left in Figure 3.15 shows the front of the trian- 
gle, and the one on the right shows the back side of the triangle. 


Why is this issue important? As you will soon see, you will often want to give the front 
and back of a polygon different physical characteristics. You can hide the back of a 
polygon altogether or give it a different color and reflective property (see Chapter 5, 
“Color, Materials, and Lighting: The Basics”). It’s important to keep the winding of all 
polygons in a scene consistent, using front-facing polygons to draw the outside surface of 
any solid objects. In the upcoming section on solid objects, we demonstrate this principle 
using some models that are more complex. 
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If you need to reverse the default behavior of OpenGL, you can do so by calling the 
following function: 


glFrontFace(GL_CW) ; 


The GL_CW parameter tells OpenGL that clockwise-wound polygons are to be considered 
front facing. To change back to counterclockwise winding for the front face, use GL_CCW. 


Triangle Strips 

For many surfaces and shapes, you need to draw several connected triangles. You can save 
a lot of time by drawing a strip of connected triangles with the GL_TRIANGLE_STRIP primi- 
tive. Figure 3.16 shows the progression of a strip of three triangles specified by a set of five 
vertices numbered VO through V4. Here, you see the vertices are not necessarily traversed 
in the same order they were specified. The reason for this is to preserve the winding 
(counterclockwise) of each triangle. The pattern is VO, V1, V2; then V2, V1, V3; then V2, 
V3, V4; and so on. 


V3 


Vo Yo Yo 


FIGURE 3.16 The progression of aGL_TRIANGLE_STRIP. 


For the rest of the discussion of polygonal primitives, we don’t show any more code frag- 
ments to demonstrate the vertices and the g1Begin statements. You should have the swing 
of things by now. Later, when we have a real sample program to work with, we resume the 
examples. 


There are two advantages to using a strip of triangles instead of specifying each triangle 
separately. First, after specifying the first three vertices for the initial triangle, you need to 
specify only a single point for each additional triangle. This saves a lot of program or data 
storage space when you have many triangles to draw. The second advantage is mathemati- 
cal performance and bandwidth savings. Fewer vertices mean a faster transfer from your 
computer’s memory to your graphics card and fewer vertex transformations (see Chapters 
2 and 4). 
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TIP 
Another advantage to composing large flat surfaces out of several smaller triangles is that when 


lighting effects are applied to the scene, OpenGL can better reproduce the simulated effects. 
You'll learn more about lighting in Chapter 5. 


Triangle Fans 

In addition to triangle strips, you can use GL_TRIANGLE_FAN to produce a group of 
connected triangles that fan around a central point. Figure 3.17 shows a fan of three trian- 
gles produced by specifying four vertices. The first vertex, VO, forms the origin of the fan. 
After the first three vertices are used to draw the initial triangle, all subsequent vertices are 
used with the origin (VO) and the vertex immediately preceding it (Vn-1) to form the next 
triangle. 


Yo Yo 


FIGURE 3.17 The progression of GL_TRIANGLE_FAN. 


Building Solid Objects 


Composing a solid object out of triangles (or any other polygon) involves more than 
assembling a series of vertices in a 3D coordinate space. Let’s examine the sample program 
TRIANGLE, which uses two triangle fans to create a cone in our viewing volume. The first 
fan produces the cone shape, using the first vertex as the point of the cone and the 
remaining vertices as points along a circle further down the z-axis. The second fan forms a 
circle and lies entirely in the xy plane, making up the bottom surface of the cone. 


The output from TRIANGLE is shown in Figure 3.18. Here, you are looking directly down 
the z-axis and can see only a circle composed of a fan of triangles. The individual triangles 
are emphasized by coloring them alternately green and red. 


The code for the SetupRC and RenderScene functions is shown in Listing 3.8. (This listing 
contains some unfamiliar variables and specifiers that are explained shortly.) This program 
demonstrates several aspects of composing 3D objects. Right-click in the window, and you 


Building Solid Objects 


will notice an Effects menu; it will be used to enable and disable some 3D drawing features 
so we can explore some of the characteristics of 3D object creation. We describe these 
features as we progress. 


Triangle Culling Example 
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FIGURE 3.18 Initial output from the TRIANGLE sample program. 


LISTING 3.8 SetupRC and RenderScene Code for the TRIANGLE Sample Program 


// This function does any needed initialization on the rendering 
// context. 
void SetupRC() 

{ 

// Black background 

glClearColor(0.0f, 0.0f, @.Of, 1.0f ); 


// Set drawing color to green 
glColor3f(0.0f, 1.0f, 0.0f); 


// Set color shading model to flat 
glShadeModel (GL_FLAT) ; 


// Clockwise-wound polygons are front facing; this is reversed 
// because we are using triangle fans 

glFrontFace(GL_CW) ; 

} 


// Called to draw scene 

void RenderScene(void) 
{ 
GLfloat x,y,angle; // Storage for coordinates and angles 
int iPivot = 1; // Used to flag alternating colors 
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LISTING 3.8 Continued 


// Clear the window and the depth buffer 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 


// Turn culling on if flag is set 
if (bCull) 

glEnable(GL_CULL_FACE) ; 
else 

glDisable(GL_CULL_FACE) ; 


// Enable depth testing if flag is set 
if (bDepth) 

glEnable(GL_DEPTH_TEST) ; 
else 

glDisable(GL_DEPTH_TEST) ; 


// Draw the back side as a wireframe only, if flag is set 
if (bOutline) 

glPolygonMode(GL_BACK,GL_LINE) ; 
else 

glPolygonMode(GL_BACK,GL_FILL) ; 


// Save matrix state and do the rotation 
glPushMatrix(); 

glRotatef(xRot, 1.0f, 0.0f, 0.0f); 
glRotatef(yRot, @.0f, 1.0f, 0.0f); 


// Begin a triangle fan 
glBegin(GL_TRIANGLE_FAN) ; 


// Pinnacle of cone is shared vertex for fan, moved up z-axis 
// to produce a cone instead of a circle 
glVertex3f(0.0f, 0.0f, 75.0f); 


// Loop around in a circle and specify even points along the circle 
// as the vertices of the triangle fan 
for(angle = @.0f; angle < (2.0f*GL_PI); angle += (GL_PI/8.0f)) 

{ 

// Calculate x and y position of the next vertex 

x = 50.0f*sin(angle) ; 

y = 50.0f*cos(angle) ; 


Building Solid Objects 115 


LISTING 3.8 Continued 


// Alternate color between red and green 
if((iPivot %2) == Q) 

glColor3f(@.0f, 1.0f, 0.0f); 
else 

glColor3f(1.0f, 0.0f, 0.0f); 


// Increment pivot to change color next time 
iPivott+; 


// Specify the next vertex for the triangle fan 
glVertex2f(x, y); 
} 


// Done drawing fan for cone 
glEnd(); 


// Begin a new triangle fan to cover the bottom 
glBegin(GL_TRIANGLE_FAN) ; 


// Center of fan is at the origin 
glVertex2f(0.0f, 0.0f); 
for(angle = 0.0f; angle < (2.@f*GL_PI); angle += (GL_PI/8.0f)) 
{ 
// Calculate x and y position of the next vertex 
x = 50.0f*sin(angle) ; 
y = 50.0f*cos(angle) ; 


// Alternate color between red and green 
if((iPivot %2) == 0) 

glColor3f(0.0f, 1.0f, 0.0f); 
else 

glColor3f(1.0f, 0.0f, 0.0f); 


// Increment pivot to change color next time 
iPivott+; 


// Specify the next vertex for the triangle fan 
glVertex2f(x, y); 
} 
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LISTING 3.8 Continued 


// Done drawing the fan that covers the bottom 
glEnd(); 


// Restore transformations 
glPopMatrix(); 


// Flush drawing commands 
glFlush(); 
} 


Setting Polygon Colors 

Until now, we have set the current color only once and drawn only a single shape. Now, 
with multiple polygons, things get slightly more interesting. We want to use different 
colors so we can see our work more easily. Colors are actually specified per vertex, not per 
polygon. The shading model affects whether the polygon is solidly colored (using the 
current color selected when the last vertex was specified) or smoothly shaded between the 
colors specified for each vertex. 


The line 
glShadeModel(GL_FLAT) ; 


tells OpenGL to fill the polygons with the solid color that was current when the polygon’s 
last vertex was specified. This is why we can simply change the current color to red or 
green before specifying the next vertex in our triangle fan. On the other hand, the line 


glShadeModel (GL_SMOOTH) ; 


would tell OpenGL to shade the triangles smoothly from each vertex, attempting to inter- 
polate the colors between those specified for each vertex. You'll learn much more about 
color and shading in Chapter S. 


Hidden Surface Removal 

Hold down one of the arrow keys to spin the cone around, and don’t select anything from 
the Effects menu yet. You’ll notice something unsettling: The cone appears to be swinging 
back and forth plus and minus 180°, with the bottom of the cone always facing you, but 
not rotating a full 360°. Figure 3.19 shows this effect more clearly. 
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FIGURE 3.19 The rotating cone appears to be wobbling back and forth. 


This wobbling happens because the bottom of the cone is drawn after the sides of the 
cone are drawn. No matter how the cone is oriented, the bottom is drawn on top of it, 
producing the “wobbling” illusion. This effect is not limited to the various sides and parts 
of an object. If more than one object is drawn and one is in front of the other (from the 
viewer's perspective), the last object drawn still appears over the previously drawn object. 


You can correct this peculiarity with a simple feature called depth testing. Depth testing is 
an effective technique for hidden surface removal, and OpenGL has functions that do this 
for you behind the scenes. The concept is simple: When a pixel is drawn, it is assigned a 
value (called the z value) that denotes its distance from the viewer's perspective. Later, 
when another pixel needs to be drawn to that screen location, the new pixel’s z value is 
compared to that of the pixel that is already stored there. If the new pixel’s z value is 
higher, it is closer to the viewer and thus in front of the previous pixel, so the previous 
pixel is obscured by the new pixel. If the new pixel’s z value is lower, it must be behind 
the existing pixel and thus is not obscured. This maneuver is accomplished internally by a 
depth buffer with storage for a depth value for every pixel on the screen. Most all of the 
samples in this book use depth testing. 


To enable depth testing, simply call 
glEnable(GL_DEPTH_TEST) ; 


Depth testing is enabled in Listing 3.8 when the bDepth variable is set to True, and it is 
disabled if bDepth is False: 


// Enable depth testing if flag is set 
if (bDepth) 

glEnable(GL_DEPTH_TEST) ; 
else 

glDisable(GL_DEPTH_TEST) ; 
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The bDepth variable is set when you select Depth Test from the Effects menu. In addition, 
the depth buffer must be cleared each time the scene is rendered. The depth buffer is anal- 
ogous to the color buffer in that it contains information about the distance of the pixels 
from the observer. This information is used to determine whether any pixels are hidden by 
pixels closer to the observer: 


// Clear the window and the depth buffer 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


A right-click with the mouse opens a pop-up menu that allows you to toggle depth testing 
on and off. Figure 3.20 shows the TRIANGLE program with depth testing enabled. It also 
shows the cone with the bottom correctly hidden behind the sides. You can see that depth 
testing is practically a prerequisite for creating 3D objects out of solid polygons. 


Triangle Culling Example 


FIGURE 3.20 The bottom of the cone is now correctly placed behind the sides for this orien- 
tation. 


Culling: Hiding Surfaces for Performance 


You can see that there are obvious visual advantages to not drawing a surface that is 
obstructed by another. Even so, you pay some performance overhead because every pixel 
drawn must be compared with the previous pixel’s z value. Sometimes, however, you know 
that a surface will never be drawn anyway, so why specify it? Culling is the term used to 
describe the technique of eliminating geometry that we know will never be seen. By not 
sending this geometry to your OpenGL driver and hardware, you can make significant 
performance improvements. One culling technique is backface culling, which eliminates 
the backsides of a surface. 


In our working example, the cone is a closed surface, and we never see the inside. OpenGL 
is actually (internally) drawing the back sides of the far side of the cone and then the front 
sides of the polygons facing us. Then, by a comparison of z buffer values, the far side of 
the cone is either overwritten or ignored. Figures 3.21a and 3.21b show our cone at a 
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particular orientation with depth testing turned on (a) and off (b). Notice that the green 
and red triangles that make up the cone sides change when depth testing is enabled. 
Without depth testing, the sides of the triangles at the far side of the cone show through. 


Triangle Culling Example 


yN 


FIGURE 3.21A_ With depth testing. 


Triangle Culling Example 


FIGURE 3.21B Without depth testing. 


Earlier in the chapter, we explained how OpenGL uses winding to determine the front and 
back sides of polygons and that it is important to keep the polygons that define the 
outside of our objects wound in a consistent direction. This consistency is what allows us 
to tell OpenGL to render only the front, only the back, or both sides of polygons. By elim- 
inating the back sides of the polygons, we can drastically reduce the amount of necessary 
processing to render the image. Even though depth testing will eliminate the appearance 
of the inside of objects, internally OpenGL must take them into account unless we explic- 
itly tell it not to. 


Backface culling is enabled or disabled for our program by the following code from 
Listing 3.8: 


// Clockwise-wound polygons are front facing; this is reversed 
// because we are using triangle fans 
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glFrontFace(GL_Cw) ; 


// Turn culling on if flag is set 
if (bCull) 

glEnable(GL_CULL_FACE); 
else 

glDisable(GL_CULL_FACE) ; 


Note that we first changed the definition of front-facing polygons to assume clockwise 
winding (because our triangle fans are all wound clockwise). 


Figure 3.22 demonstrates that the bottom of the cone is gone when culling is enabled. The 
reason is that we didn’t follow our own rule about all the surface polygons having the 
same winding. The triangle fan that makes up the bottom of the cone is wound clockwise, 
like the fan that makes up the sides of the cone, but the front side of the cone’s bottom 
section is then facing the inside (see Figure 3.23). 


Triangle Culling Example 


FIGURE 3.22 The bottom of the cone is culled because the front-facing triangles are inside. 


Front-facing 
triangles 


: ' Front-facing 
triangles 


FIGURE 3.23 How the cone was assembled from two triangle fans. 


Building Solid Objects 


We could have corrected this problem by changing the winding rule, by calling 
glFrontFace(GL_CCW) ; 


just before we drew the second triangle fan. But in this example, we wanted to make it 
easy for you to see culling in action, as well as set up for our next demonstration of 
polygon tweaking. 


WHY DO WE NEED BACKFACE CULLING? 


You might wonder, “If backface culling is so desirable, why do we need the ability to turn it on 
and off?” Backface culling is useful when drawing closed objects or solids, but you won’t always 
be rendering these types of geometry. Some flat objects (such as paper) can still be seen from 
both sides. If the cone we are drawing here were made of glass or plastic, you would actually be 
able to see the front and the back sides of the geometry. (See Chapter 6 for a discussion of 
drawing transparent objects.) 


Polygon Modes 

Polygons don’t have to be filled with the current color. By default, polygons are drawn 
solid, but you can change this behavior by specifying that polygons are to be drawn as 
outlines or just points (only the vertices are plotted). The function glPolygonMode allows 
polygons to be rendered as filled solids, as outlines, or as points only. In addition, you can 
apply this rendering mode to both sides of the polygons or only to the front or back. The 
following code from Listing 3.8 shows the polygon mode being set to outlines or solid, 
depending on the state of the Boolean variable bOutline: 


// Draw back side as a polygon only, if flag is set 
if (bOutline) 

g1lPolygonMode(GL_BACK,GL_LINE) ; 
else 

glPolygonMode(GL_BACK,GL_FILL); 


Figure 3.24 shows the back sides of all polygons rendered as outlines. (We had to disable 
culling to produce this image; otherwise, the inside would be eliminated and you would 
get no outlines.) Notice that the bottom of the cone is now wireframe instead of solid, and 
you can see up inside the cone where the inside walls are also drawn as wireframe trian- 
gles. 
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Triangle Culling Example 


FIGURE 3.24 Using glPolygonMode to render one side of the triangles as outlines. 


Other Primitives 


Triangles are the preferred primitive for object composition because most OpenGL hard- 
ware specifically accelerates triangles, but they are not the only primitives available. Some 
hardware provides for acceleration of other shapes as well, and programmatically, using a 
general-purpose graphics primitive might be simpler. The remaining OpenGL primitives 
provide for rapid specification of a quadrilateral or quadrilateral strip, as well as a general- 
purpose polygon. 


Four-Sided Polygons: Quads 


If you add one more side to a triangle, you get a quadrilateral, or a four-sided figure. 
OpenGL’s GL_QUADS primitive draws a four-sided polygon. In Figure 3.25, a quad is drawn 
from four vertices. Note also that these quads have clockwise winding. One important rule 
to bear in mind when you use quads is that all four corners of the quadrilateral must lie in 
a plane (no bent quads!). 
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FIGURE 3.25 An example of GL_QUADS. 
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Quad Strips 

As you can for triangle strips, you can specify a strip of connected quadrilaterals with the 
GL_QUAD_STRIP primitive. Figure 3.26 shows the progression of a quad strip specified by six 
vertices. Note that these quad strips maintain a clockwise winding. 
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FIGURE 3.26 Progression of GL_QUAD_STRIP. 


General Polygons 


The final OpenGL primitive is the GL_POLYGON, which you can use to draw a polygon 
having any number of sides. Figure 3.27 shows a polygon consisting of five vertices. 
Polygons, like quads, must have all vertices on the same plane. An easy way around this 
tule is to substitute GL_TRIANGLE_FAN for GL_POLYGON! 
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FIGURE 3.27 Progression of GL_POLYGON. 


WHAT ABOUT RECTANGLES? 


All 10 of the OpenGL primitives are used with g1Begin/glEnd to draw general-purpose polygonal 
shapes. Although in Chapter 2, we used the function glRect as an easy and convenient mecha- 
nism for specifying 2D rectangles, henceforth we will resort to using GL_QUADS. 


Filling Polygons, or Stippling Revisited 


There are two methods for applying a pattern to solid polygons. The customary method is 
texture mapping, in which an image is mapped to the surface of a polygon, and this is 
covered in Chapter 8, “Texture Mapping: The Basics.” Another way is to specify a stippling 
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pattern, as we did for lines. A polygon stipple pattern is nothing more than a 32x32 
monochrome bitmap that is used for the fill pattern. 


To enable polygon stippling, call 


glEnable(GL_POLYGON_STIPPLE) ; 


and then call 


glPolygonStipple(pBitmap) ; 


pBitmap is a pointer to a data area containing the stipple pattern. Hereafter, all polygons 
are filled using the pattern specified by pBitmap (GLubyte *). This pattern is similar to that 
used by line stippling, except the buffer is large enough to hold a 32-by-32-bit pattern. 
Also, the bits are read with the most significant bit (MSB) first, which is just the opposite 
of line stipple patterns. Figure 3.28 shows a bit pattern for a campfire that we use for a 
stipple pattern. 


= OXIF 0x80 OX1F OXCO 


FIGURE 3.28 Building a polygon stipple pattern. 


PIXEL STORAGE 
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As you will learn in Chapter 7, “Imaging with OpenGL,” you can modify the way pixels for 
stipple patterns are interpreted by using the glPixelStore function. For now, however, we stick 


to the simple default polygon stippling. 


To construct a mask to represent this pattern, we store one row at a time from the bottom 
up. Fortunately, unlike line stipple patterns, the data is, by default, interpreted just as it is 
stored, with the most significant bit read first. Each byte can then be read from left to 
right and stored in an array of GLubyte large enough to hold 32 rows of 4 bytes apiece. 


Listing 3.9 shows the code used to store this pattern. Each row of the array represents a 
row from Figure 3.28. The first row in the array is the last row of the figure, and so on, up 


to the last row of the array and the first row of the figure. 


LISTING 3.9 Mask Definition for the Campfire in Figure 3.28 


// Bitmap of campfire 
GLubyte fire[] = { 0x00, 
0x00, 
0x00, 
0x00, 
Qx00, 
0x00, 
0x00, 
0x00, 
0x00, 
OxOf, 
Oxif, 
Oxf, 
x07, 
0x03, 
0x03, 
0x07, 
Oxtf, 
Oxff, 
Oxde, 
x71, 
0x03, 
0x02, 
0x05, 
0x02, 
0xe2, 
0xe2, 


0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x80, 
Oxc®, 
Oxe®, 
Oxfo, 
Oxf5, 
Oxfd, 
Oxfc, 
Qxe3, 
x80, 
0x10, 
x10, 
0x88, 
0x5, 
x82, 
0x40, 
0x64, 


0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
x01, 
0x07, 
Oxtf, 
Oxif, 
Ox3f, 
Qx7e, 
Oxff, 
Oxff, 
Oxff, 
Oxff, 
Oxbf, 
Q@xb7, 
Qx4a, 
Qx4e, 
Q@x8c, 
0x04, 
x14, 
0x10, 
Q@x1a, 


0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
0x00, 
Qxcd, 
Oxfo, 
Oxfo, 
xed, 
Qxcd, 
0x80, 
0x00, 
0x80, 
xed, 
Oxf8, 
Oxe8, 
0x70, 
0x00, 
0x80, 
0x40, 
0x20, 
0x40, 
0x40, 
0x80, 
0x80, 


125 


126 


CHAPTER 3 Drawing in Space: Geometric Primitives and Buffers 


LISTING 3.9 Continued — yee _ 


@x@0, @x92, Ox29, 0x00, 
@x@0, Oxb@, 0x48, 0x00, 
@x00, O@xc8, 0x90, 0x00, 
@x00, Ox85, 0x10, 0x00, 
@x@0, 0x03, Ox00, 0x00, 
Qx@0, O@x00, Ox10, 0x00 }; 


To make use of this stipple pattern, we must first enable polygon stippling and then 
specify this pattern as the stipple pattern. The PSTIPPLE sample program does this and 
then draws an octagon using the stipple pattern. Listing 3.10 shows the pertinent code, 
and Figure 3.29 shows the output from PSTIPPLE. 


: Polygon Stippling 


FIGURE 3.29 Output from the PSTIPPLE program. 


LISTING 3.10 Code from PSTIPPLE That Draws a Stippled Octagon 


// This function does any needed initialization on the rendering 
// context. 
void SetupRC() 

{ 

// Black background 

glClearColor(0.0f, @.0f, 0.0f, 1.0f ); 


// Set drawing color to red 
glColor3f(1.0f, 0.0f, @.0f); 


// Enable polygon stippling 
glEnable(GL_POLYGON_STIPPLE) ; 
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LISTING 3.10 Continued 


// Specify a specific stipple pattern 
glPolygonStipple(fire) ; 
} 


// Called to draw scene 
void RenderScene (void) 
{ 
// Clear the window 
glClear(GL_COLOR_BUFFER_BIT) ; ~ 


// Begin the stop sign shape, 
// use a standard polygon for simplicity 
glBegin(GL_POLYGON) ; 
glVertex2f(-20.0f, 50.0f); 
glVertex2f(20.0f, 50.0f); 
glVertex2f(50.0f, 20.0f); 
glVertex2f(50.0f, -20.0f); 
glVertex2f(20.0f, -50.0f); 
glVertex2f(-20.0f, -50.0f); 
glVertex2f(-50.0f, -20.0f); 
glVertex2f(-50.0f, 20.0f); 
glEnd() ; 


// Flush drawing commands 
glFlush(); 
} 


Figure 3.30 shows the octagon rotated somewhat. Notice that the stipple pattern is still 
used, but the pattern is not rotated with the polygon. The stipple pattern is used only for 
simple polygon filling onscreen. If you need to map an image to a polygon so that it 
mimics the polygon’s surface, you must use texture mapping (see Chapter 8). 
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? Polygon Stippling 


FIGURE 3.30 PSTIPPLE output with the polygon rotated, showing that the stipple pattern is 
not rotated. 


Polygon Construction Rules 
When you are using many polygons to construct a complex surface, you need to remem- 
ber two important rules. 


The first rule is that all polygons must be planar. That is, all the vertices of the polygon 
must lie in a single plane, as illustrated in Figure 3.31. The polygon cannot twist or bend 
in space. 


Planar polygon Nonplanar polygon 


FIGURE 3.31 Planar versus nonplanar polygons. 


Here is yet another good reason to use triangles. No triangle can ever be twisted so that all 
three points do not line up in a plane because mathematically it only takes exactly three 
points to define a plane. (If you can plot an invalid triangle, aside from winding it in the 
wrong direction, the Nobel Prize committee might be looking for you!) 


The second rule of polygon construction is that the polygon’s edges must not intersect, 
and the polygon must be convex. A polygon intersects itself if any two of its lines cross. 
Convex means that the polygon cannot have any indentions. A more rigorous test of a 
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convex polygon is to draw some lines through it. If any given line enters and leaves the 
polygon more than once, the polygon is not convex. Figure 3.32 gives examples of good 
and bad polygons. 


Valid polygons Invalid polygons 


FIGURE 3.32 Some valid and invalid primitive polygons. 


WHY THE LIMITATIONS ON POLYGONS? 


You might wonder why OpenCL places the restrictions on polygon construction. Handling poly- 
gons can become quite complex, and OpenGL’s restrictions allow it to use very fast algorithms 
for rendering these polygons. We predict that you'll not find these restrictions burdensome and 
that you'll be able to build any shapes or objects you need using the existing primitives. Chapter 
10, “Curves and Surfaces,” discusses some techniques for breaking a complex shape into smaller 
triangles. 


Subdivision and Edges 

Even though OpenGL can draw only convex polygons, there’s still a way to create a 
nonconvex polygon: by arranging two or more convex polygons together. For example, 
let’s take a four-point star, as shown in Figure 3.33. This shape is obviously not convex 
and thus violates OpenGL’s rules for simple polygon construction. However, the star on 
the right is composed of six separate triangles, which are legal polygons. 


When the polygons are filled, you won’t be able to see any edges and the figure will seem 
to be a single shape onscreen. However, if you use g1PolygonMode to switch to an outline 
drawing, it is distracting to see all those little triangles making up some larger surface area. 


OpenGL provides a special flag called an edge flag to address those distracting edges. By 
setting and clearing the edge flag as you specify a list of vertices, you inform OpenGL 
which line segments are considered border lines (lines that go around the border of your 
shape) and which ones are not (internal lines that shouldn’t be visible). The glEdgeFlag 
function takes a single parameter that sets the edge flag to True or False. When the func- 
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tion is set to True, any vertices that follow mark the beginning of a boundary line 
segment. Listing 3.11 shows an example of this from the STAR sample program on 
the CD. 


FIGURE 3.33 A nonconvex four-point star made up of six triangles. 


LISTING 3.11 Sample Usage of glEdgeFlag from the STAR Program 


// Begin the triangles 
glBegin(GL_TRIANGLES) ; 


glEdgeFlag(bEdgeFlag) ; 
glVertex2f(-20.0f, 0.0f); 
glEdgeFlag(TRUE) ; 
glVertex2f(20.0f, 0.0f); 
glVertex2f(@.0f, 40.0f); 


glVertex2f(-20.0f ,0.0f) ; 
glVertex2f (-60.0f, -20.0f); 
glEdgeFlag(bEdgeFlag) ; 
glVertex2f (-20.0f, -40.0f); 
glEdgeFlag(TRUE) ; 


glVertex2f (-20.0f, -40.0f); 
glVertex2f(@.0f, -80.0f); 
glEdgeFlag(bEdgeFlag) ; 
glVertex2f(20.0f, -40.0f); 
glEdgeFlag(TRUE) ; 
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LISTING 3.11 Continued 


glVertex2f(20.0f, -40.0f); 
glVertex2f(60.0f, -20.0f); 
glEdgeFlag(bEdgeFlag) ; 
glVertex2f(20.0f, 0.0f); 
glEdgeFlag(TRUE) ; 


// Center square as two triangles 

glEdgeFlag(bEdgeFlag) ; 

glVertex2f(-20.0f, 0.0f); 

glVertex2f(-20.0f, -40.0f); Ww 
glVertex2f(20.0f, @.0f); 


glVertex2f (-20.0f, -40.0f); 
glVertex2f(20.0f, -40.0f); 
glVertex2f(20.0f, 0.0f); 
glEdgeFlag(TRUE) ; 


// Done drawing Triangles 
glEnd(); 


The Boolean variable bEdgeFlag is toggled on and off by a menu option to make the edges 
appear and disappear. If this flag is True, all edges are considered boundary edges and 
appear when the polygon mode is set to GL_LINES. In Figures 3.34a and 3.34b, you can see 
the output from STAR, showing the wireframe star with and without edges. 


Sold and Outlined Star 


FIGURE 3.34A STAR program with edges enabled. 
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Solid and Outlined Star 


FIGURE 3.34B STAR program without edges enabled. 


Other Buffer Tricks 


You learned from Chapter 2 that OpenGL does not render (draw) these primitives directly 
on the screen. Instead, rendering is done in a buffer, which is later swapped to the screen. 
We refer to these two buffers as the front (the screen) and back color buffers. By default, 
OpenGL commands are rendered into the back buffer, and when you call 
glutSwapBuffers (or your operating system-specific buffer swap function), the front and 
back buffers are swapped so that you can see the rendering results. You can, however, 
render directly into the front buffer if you want. This capability can be useful for display- 
ing a series of drawing commands so that you can see some object or shape actually being 
drawn. There are two ways to do this; both are discussed in the following section. 


Using Buffer Targets 


The first way to render directly into the front buffer is to just tell OpenGL that you want 
drawing to be done there. You do this by calling the following function: 


void glDrawBuffer(Glenum mode) ; 


Specifying GL_FRONT causes OpenGL to render to the front buffer, and GL_BACK moves 
rendering back to the back buffer. OpenGL implementations can support more than just a 
single front and back buffer for rendering, such as left and right buffers for stereo render- 
ing, and auxiliary buffers. These other buffers are documented further in the reference 
section at the end of this chapter. 


The second way to render to the front buffer is to simply not request double-buffered 
rendering when OpenGL is initialized. OpenGL is initialized differently on each OS plat- 
form, but with GLUT, we initialize our display mode for RGB color and double-buffered 
rendering with the following line of code: 


glutInitDisplayMode(GLUT_DOUBLE | GLUT_RGB); 


Other Buffer Tricks 


To get single-buffered rendering, you simply omit the bit flag GLUT_DOUBLE, as shown here: 
glutInitDisplayMode(GLUT_RGB) ; 


When you do single-buffered rendering, it is important to call either glFlush or glFinish 
whenever you want to see the results actually drawn to screen. A buffer swap implicitly 
performs a flush of the pipeline and waits for rendering to complete before the swap actu- 
ally occurs. We’ll discuss the mechanics of this process in more detail in Chapter 11, “It’s 
All About the Pipeline: Faster Geometry Throughput.” 


Listing 3.12 shows the drawing code for the sample program SINGLE. This example uses a 
single rendering buffer to draw a series of points spiraling out from the center of the 
window. The RenderScene() function is called repeatedly and uses static variables to cycle 
through a simple animation. The output of the SINGLE sample program is shown in 
Figure 3.35. 


FIGURE 3.35 Output from the single-buffered rendering example. 


LISTING 3.12 Drawing Code for the SINGLE Sample _ 


FULTETTTT TTT TTT TT TT TT TTT 
// Called to draw scene 
void RenderScene(void) 


{ 
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LISTING 3.12 Continued 


static GLdouble dRadius = 0.1; 
static GLdouble dAngle = 0.0; 


// Clear blue window 
glClearColor(0.0f, 0.0f, 1.0f, 0.0f); 


if(dAngle == 0.0) 
glClear(GL_COLOR_BUFFER_BIT) ; 


glBegin(GL_POINTS) ; 
glVertex2d(dRadius * cos(dAngle), dRadius * sin(dAngle)); 
glEnd(); 


dRadius *= 1.01; 
dAngle += 0.1; 


if(dAngle > 30.0) 


{ 
dRadius = 0.1; 
dAngle = 0.0; 
} 

glFlush(); 


} 


Manipulating the Depth Buffer 

The color buffers are not the only buffers that OpenGL renders into. In the preceding 
chapter, we mentioned other buffer targets, including the depth buffer. However, the 
depth buffer is filled with depth values instead of color values. Requesting a depth buffer 
with GLUT is as simple as adding the GLUT_DEPTH bit flag when initializing the display 
mode: 


glutInitDisplayMode(GLUT_RGB | GLUT_DOUBLE | GLUT_DEPTH); 

You've already seen that enabling the use of the depth buffer for depth testing is as easy as 
calling the following: 

glEnable(GL_DEPTH_TEST) ; 


Even when depth testing is not enabled, if a depth buffer is created, OpenGL will write 
corresponding depth values for all color fragments that go into the color buffer. 


Other Buffer Tricks 


Sometimes, though, you may want to temporarily turn off writing values to the depth 
buffer as well as depth testing. You can do this with the function g1DepthMask: 


void glDepthMask(GLboolean mask); 


Setting the mask to GL_FALSE disables writes to the depth buffer but does not disable 
depth testing from being performed using any values that have already been written to 
the depth buffer. Calling this function with GL_TRUE re-enables writing to the depth buffer, 
which is the default state. Masking color writes is also possible but a bit more involved, 
and will be discussed in Chapter 6. 


Cutting It Out with Scissors 


One way to improve rendering performance is to update only the portion of the screen 
that has changed. You may also need to restrict OpenGL rendering to a smaller rectangular 
region inside the window. OpenGL allows you to specify a scissor rectangle within your 
window where rendering can take place. By default, the scissor rectangle is the size of the 
window, and no scissor test takes place. You turn on the scissor test with the ubiquitous 
glEnable function: 


glEnable(GL_SCISSOR_TEST) ; 


You can, of course, turn off the scissor test again with the corresponding glDisable func- 
tion call. The rectangle within the window where rendering is performed, called the scissor 
box, is specified in window coordinates (pixels) with the following function: 


void glScissor(GLint x, GLint y, GLsizei width, GLsizei height); 


The x and y parameters specify the lower-left corner of the scissor box, with width and 
height being the corresponding dimensions of the scissor box. Listing 3.13 shows the 
rendering code for the sample program SCISSOR. This program clears the color buffer 
three times, each time with a smaller scissor box specified before the clear. The result is a 
set of overlapping colored rectangles, as shown in Figure 3.36. 


LISTING 3.13 Using the Scissor Box to Render a Series of Rectangles 


void RenderScene(void) 
{ 
// Clear blue window 
glClearColor(0.0f, 0.0f, 1.0f, 0.0f); 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Now set scissor to smaller red sub region 
glClearColor(1.0f, 0.0f, 0.0f, 0.0f); 
glScissor(10@, 100, 600, 400); 
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LISTING 3.13 Continued 


glEnable(GL_SCISSOR_TEST) ; 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Finally, an even smaller green rectangle 
glClearColor(0.0f, 1.0f, 0.0f, 0.0f); 
glScissor(200, 200, 400, 200); 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Turn scissor back off for next render 
glDisable(GL_SCISSOR_TEST) ; 


glutSwapBuffers(); 
} 


FIGURE 3.36 Shrinking scissor boxes. 


Using the Stencil Buffer 

Using the OpenGL scissor box is a great way to restrict rendering to a rectangle within the 
window. Frequently, however, we want to mask out an irregularly shaped area using a 
stencil pattern. In the real world, a stencil is a flat piece of cardboard or other material that 
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has a pattern cut out of it. Painters use the stencil to apply paint to a surface using the 
pattern in the stencil. Figure 3.37 shows how this process works. 


FIGURE 3.37 Using a stencil to paint a surface in the real world. 


In the OpenGL world, we have the stencil buffer instead. The stencil buffer provides a 
similar capability but is far more powerful because we can create the stencil pattern 
ourselves with rendering commands. To use OpenGL stenciling, we must first request a 
stencil buffer using the platform-specific OpenGL setup procedures. When using GLUT, we 
request one when we initialize the display mode. For example, the following line of code 
sets up a double-buffered RGB color buffer with stencil: 


glutInitDisplayMode(GLUT_RGB } GLUT_DOUBLE | GLUT_STENCIL); 


The stencil operation is relatively fast on modern hardware-accelerated OpenGL imple- 
mentations, but it can also be turned on and off with glEnable/g1lDisable. For example, 
we turn on the stencil test with the following line of code: 


glEnable(GL_STENCIL_TEST) ; 


With the stencil test enabled, drawing occurs only at locations that pass the stencil test. 
You set up the stencil test that you want to use with this function: 


void glStencilFunc(GLenum func, GLint ref, GLuint mask); 


The stencil function that you want to use, func, can be any one of these values: GL_NEVER, 
GL_ALWAYS, GL_LESS, GL_LEQUAL, GL_EQUAL, GL_GEQUAL, GL_GREATER, and GL_NOTEQUAL. These 
values tell OpenGL how to compare the value already stored in the stencil buffer with the 
value you specify in ref. These values correspond to never or always passing, passing if the 
reference value is less than, less than or equal, greater than or equal, greater than, and not 
equal to the value already stored in the stencil buffer, respectively. In addition, you can 
specify a mask value that is bit-wise ANDed with both the reference value and the value 
from the stencil buffer before the comparison takes place. 
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STENCIL BITS 


You need to realize that the stencil buffer may be of limited precision. Stencil buffers are typically 
only between 1 and 8 bits deep. Each OpenGL implementation may have its own limits on the 
available bit depth of the stencil buffer, and each operating system or environment has its own 
methods of querying and setting this value. In GLUT, you just get the most stencil bits available, 
but for finer-grained control, you need to refer to the operating system-specific chapters later in 
the book. Values passed to ref and mask that exceed the available bit depth of the stencil buffer 
are simply truncated, and only the maximum number of least significant bits is used. 


Creating the Stencil Pattern 

You now know how the stencil test is performed, but how are values put into the stencil 
buffer to begin with? First, we must make sure that the stencil buffer is cleared before we 
start any drawing operations. We do this in the same way that we clear the color and 
depth buffers with glClear—using the bit mask GL_STENCIL_BUFFER_BIT. For example, the 
following line of code clears the color, depth, and stencil buffers simultaneously: 


glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH BUFFER BIT | GL_STENCIL_BUFFER_BIT) ; 


The value used in the clear operation is set previously with a call to 


glClearStencil(GLint s); 


When the stencil test is enabled, rendering commands are tested against the value in the 
stencil buffer using the g1StencilFunc parameters we just discussed. Fragments (color 
values placed in the color buffer) are either written or discarded based on the outcome of 
that stencil test. The stencil buffer itself is also modified during this test, and what goes 
into the stencil buffer depends on how you've called the glStencil0p function: 


void glStencilOp(GLenum fail, GLenum zfail, GLenum zpass) ; 


These values tell OpenGL how to change the value of the stencil buffer if the stencil test 
fails (fail), and even if the stencil test passes, you can modify the stencil buffer if the 
depth test fails (zfail) or passes (zpass). The valid values for these arguments are GL_KEEP, 
GL_ZERO, GL_REPLACE, GL_INCR, GL_DECR, GL_INVERT, GL_INCR_WRAP, and GL_DECR_WRAP. 
These values correspond to keeping the current value, setting it to zero, replacing with the 
reference value (from glStencilFunc), incrementing or decrementing the value, inverting 
it, and incrementing/decrementing with wrap, respectively. Both GL_INCR and GL_DECR 
increment and decrement the stencil value but are clamped to the minimum and 
maximum value that can be represented in the stencil buffer for a given bit depth. 
GL_INCR_WRAP and likewise GL_DECR_WRAP simply wrap the values around when they 
exceed the upper and lower limits of a given bit representation. 


In the sample program STENCIL, we create a spiral line pattern in the stencil buffer, but 
not in the color buffer. The bouncing rectangle from Chapter 2 comes back for a visit, but 


Other Buffer Tricks 
this time, the stencil test prevents drawing of the red rectangle anywhere the stencil buffer 
contains a 0x1 value. Listing 3.14 shows the relevant drawing code. 


LISTING 3.14 Rendering Code for the STENCIL Sample 


void RenderScene(void) 


{ 
GLdouble dRadius = 0.1; // Initial radius of spiral 
GLdouble dAngle; // Looping variable 


// Clear blue window 
glClearColor(@.0f, 0.0f, 1.0f, 0.0f); 


// Use ® for clear stencil, enable stencil test 
glClearStencil(@.0f); 
glEnable(GL_STENCIL_TEST) ; 


// Clear color and stencil buffer 
glClear(GL_COLOR_BUFFER_BIT | GL_STENCIL_BUFFER_BIT); 


// All drawing commands fail the stencil test, and are not 
// drawn, but increment the value in the stencil buffer. 
glStencilFunc(GL_NEVER, @x@, 0x); 

glStencilOp(GL_INCR, GL_INCR, GL_INCR); 


// Spiral pattern will create stencil pattern 
// Draw the spiral pattern with white lines. We 
// make the lines white to demonstrate that the 
// stencil function prevents them from being drawn 
glColor3f(1.0f, 1.0f, 1.0f); 
glBegin(GL_LINE_STRIP) ; 
for(dAngle = @; dAngle < 400.0; dAngle += 0.1) 
{ 
glVertex2d(dRadius * cos(dAngle), dRadius * sin(dAngle)); 
dRadius *= 1.002; 
} 
glEnd(); 


// Now, allow drawing, except where the stencil pattern is 0x1 
// and do not make any further changes to the stencil buffer 
glStencilFunc(GL_NOTEQUAL, @x1, 0x1); 

glStencil0p(GL_KEEP, GL_KEEP, GL_KEEP); 
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LISTING 3.14 Continued 


// Now draw red bouncing square 

// (x and y) are modified by a timer function 
glColor3f(1.0f, @.0f, 0.0f); 

glRectf(x, y, x + rsize, y - rsize); 


// All done, do the buffer swap 
glutSwapBuffers(); 
} 


The following two lines cause all fragments to fail the stencil test. The values of ref and 
mask are irrelevant in this case and are not used. 


glStencilFunc(GL_NEVER, @x®, @x0); 
glStencil0p(GL_INCR, GL_INCR, GL_INCR); 


The arguments to g1Stencil0p, however, cause the value in the stencil buffer to be written 
(incremented actually), regardless of whether anything is seen on the screen. Following 
these lines, a white spiral line is drawn, and even though the color of the line is white so 
you can see it against the blue background, it is not drawn in the color buffer because it 
always fails the stencil test (GL_NEVER). You are essentially rendering only to the stencil 
buffer! 


Next, we change the stencil operation with these lines: 


glStencilFunc(GL_NOTEQUAL, @x1, 0x1); 
glStencilOp(GL_KEEP, GL_KEEP, GL_KEEP); 


Now, drawing will occur anywhere the stencil buffer is not equal (GL_NOTEQUAL) to Ox1, 
which is anywhere onscreen that the spiral line is not drawn. The subsequent call to 
glStencilOp is optional for this example, but it tells OpenGL to leave the stencil buffer 
alone for all future drawing operations. Although this sample is best seen in action, Figure 
3.38 shows an image of what the bounding red square looks like as it is “stenciled out.” 


Just like the depth buffer, you can also mask out writes to the stencil buffer by using the 
function glStencilMask: 


void glStencilMake(GLboolean mask) ; 


Setting the mask to false does not disable stencil test operations but does prevent any 
operation from writing values into the stencil buffer. 


Summary 


FIGURE 3.38 The bouncing red square with masking stencil pattern. 


Summary 


We covered a lot of ground in this chapter. At this point, you can create your 3D space for 
rendering, and you know how to draw everything from points and lines to complex poly- 
gons. We also showed you how to assemble these two-dimensional primitives as the 
surface of three-dimensional objects. 


You also learned about some of the other buffers that OpenGL renders into besides the 
color buffer. As we move forward throughout the book, we will use the depth and stencil 
buffers for many other techniques and special effects. In Chapter 6, you will learn about 
yet another OpenGL buffer, the Accumulation buffer. You’ll see later that all these buffers 
working together can create some outstanding and very realistic 3D graphics. 


We encourage you to experiment with what you have learned in this chapter. Use your 
imagination and create some of your own 3D objects before moving on to the rest of the 
book. You'll then have some personal samples to work with and enhance as you learn and 
explore new techniques throughout the book. 
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Reference 


glBegin 


Purpose: 


Include File: 
Syntax: 


Denotes the beginning of a group of vertices that define one or more 
primitives. 


<gl.h> 


void glBegin(GLenum mode) ; 


Description: This function is used in conjunction with glEnd to delimit the vertices of 
an OpenGL primitive. You can include multiple vertices sets within a 
single glBegin/glEnd pair, as long as they are for the same primitive type. 
You can also make other settings with additional OpenGL commands 
that affect the vertices following them. You can call only these OpenGL 
functions within a glBegin/glEnd sequence: glVertex, glColor, 
glNormal, glEvalCoord, glCallList, g1CallLists, glTexCoord, 
glEdgeFlag, and glMaterial. Note that display lists (g1CallList(s)) may 
only contain the other functions listed here. 

Parameters: 

mode GLenum: This value specifies the primitive to be constructed. It can be any 
of the values in Table 3.1. 

TABLE 3.1 OpenGL Primitives Supported by glBegin 

Mode Primitive Type 
GL_POINTS The specified vertices are used to create a single point each. 
GL_LINES The specified vertices are used to create line segments. Every two vertices 


GL_LINE_STRIP 


GL_LINE_LOOP 


GL_TRIANGLES 


specify a single and separate line segment. If the number of vertices is odd, 
the last one is ignored. 

The specified vertices are used to create a line strip. After the first vertex, each 
subsequent vertex specifies the next point to which the line is extended. 

This mode behaves like GL_LINE_STRIP, except a final line segment is drawn 
between the last and the first vertex specified. This is typically used to draw 
closed regions that might violate the rules regarding GL_POLYGON usage. 

The specified vertices are used to construct triangles. Every three vertices 
specify a new triangle. If the number of vertices is not evenly divisible by 
three, the extra vertices are ignored. 


GL_TRIANGLE_STRIP The specified vertices are used to create a strip of triangles. After the first 


three vertices are specified, each of any subsequent vertices is used with the 
two preceding ones to construct the next triangle. Each triplet of vertices 
(after the initial set) is automatically rearranged to ensure consistent winding 
of the triangles. 


Reference 


Mode Primitive Type 


GL_TRIANGLE_FAN The specified vertices are used to construct a triangle fan. The first vertex 
serves as an origin, and each vertex after the third is combined with the fore- 
going one and the origin. Any number of triangles may be fanned in this 
manner. 

GL_QUADS Each set of four vertices is used to construct a quadrilateral (a four-sided 
polygon). If the number of vertices is not evenly divisible by four, the remain- 
ing ones are ignored. 

GL_QUAD_STRIP The specified vertices are used to construct a strip of quadrilaterals. One 
quadrilateral is defined for each pair of vertices after the first pair. Unlike the 
vertex ordering for GL_QUADS, each pair of vertices is used in the reverse order 
specified to ensure consistent winding. 

GL_POLYGON The specified vertices are used to construct a convex polygon. The polygon 
edges must not intersect. The last vertex is automatically connected to the 
first vertex to ensure the polygon is closed. 


Returns: None. 

See Also: glEnd, glVertex 

glClearDepth 

Purpose: Specifies a depth value to be used for depth buffer clears. 
Include File: <gl.h> 

Syntax: 


void glClearDepth(GLclampd depth); 


Description: This function sets the depth value that is used when clearing the depth 
buffer with glClear(GL_DEPTH_BUFFER_BIT). 


Parameters: 

depth GLclampd: The clear value for the depth buffer. 
Returns: None. 

See Also: glClear, glDepthFunc, glDepthMask, glDepthRange 


glClearStencil 


Purpose: Specifies a stencil value to be used for stencil buffer clears. 
Include File: <gl.h> 

Syntax: 

void glClearStencil(GLint value); 
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Description: This function sets the stencil value that is used when clearing the stencil 
buffer with g1Clear(GL_STENCIL_BUFFER_BIT). 

Parameters: 

value GLint: The clear value for the stencil buffer. 

Returns: None. 

See Also: glStencilFunc, glStencildp 

glCullFace 

Purpose: Specifies whether the front or back of polygons should be eliminated 


from drawing. 
Include File: <gl.h> 
Syntax: 
void glCullFace(GLenum mode) ; 


Description: This function eliminates all drawing operations on either the front or 
back of a polygon. This eliminates unnecessary rendering computations 
when the back side of polygons are never visible, regardless of rotation or 
translation of the objects. Culling is enabled or disabled by calling 
glEnable or glDisable with the GL_CULL_FACE parameter. The front and 
back of the polygon are defined by use of glFrontFace and by the order 
in which the vertices are specified (clockwise or counterclockwise 


winding). 

Parameters: 

mode GLenum: Specifies which face of polygons should be culled. May be either 
GL_FRONT or GL_BACK. 

Returns: None. 

See Also: glFrontFace, glLightModel 

glDepthFunc 

Purpose: Specifies the depth-comparison function used against the depth buffer to 


decide whether color fragments should be rendered. 
Include File: <gl.h> 
Syntax: 
void glDepthFunc(GLenum func) ; 


Description: Depth testing is the primary means of hidden surface removal in 
OpenGL. When a color value is written to the color buffer, a correspond- 
ing depth value is written to the depth buffer. When depth testing is 


Parameters: 


func 


TABLE 3.2 Depth Function Enumerants 


Reference 


enabled by calling glEnable(GL_DEPTH_TEST), color values are not written 
to the color buffer unless the corresponding depth value passes the depth 
test with the depth value already present. This function allows you to 
tweak the function used for depth buffer comparisons. The default func- 
tion is GL_LESS. 


GLenum: Specifies which depth-comparison function to use. Valid values 
are listed in Table 3.2. 


Depth Function 


GL_NEVER 
GL_LESS 


GL_LEQUAL 
GL_EQUAL 
GL_GREATER 


GL_NOTEQUAL 


Meaning 


Fragments never pass the depth test. 

Fragments pass only if the incoming z value is less than the z value already 
present in the z buffer. This is the default value. 

Fragments pass only if the incoming z value is less than or equal to the z value 
already present in the z buffer. 

Fragments pass only if the incoming z value is equal to the z value already 
present in the z buffer. 

Fragments pass only if the incoming z value is greater than the z value already 
present in the z buffer. 

Fragments pass only if the incoming z value is not equal to the z value already 
present in the z buffer. 


GL_GEQUAL Fragments pass only if the incoming z value is greater than or equal to the z 
value already present in the z buffer. 
GL_ALWAYS Fragments always pass regardless of any z value. 
Returns: None. 
See Also: glClearDepth, glDepthMask, glDepthRange 
glDepthMask 
Purpose: Selectively allows or disallows changes to the depth buffer. 


Include File: 
Syntax: 


<gl.h> 


void glDepthMask(GLBoolean flag); 


Description: 


If a depth buffer is created for an OpenGL rendering context, OpenGL 
will calculate and store depth values. Even when depth testing is 
disabled, depth values are still calculated and stored in the depth buffer 
by default. This function allows you to selectively enable and disable 
writing to the depth buffer. 
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Parameters: 

flag GLboolean: When this parameter is set to GL_TRUE, depth buffer writes are 
enabled (default). Setting this parameter to GL_FALSE disables changes to 
the depth buffer. 

Returns: None. 

See Also: glClearDepth, glDepthFunc, glDepthRange 

glDepthRange 

Purpose: Allows a mapping of z values to window coordinates from normalized 
device coordinates. 

Include File: <gl.h> 

Syntax: 


void glDepthRange(GLclampd zNear, GLclampd zFar); 


Description: Normally, depth buffer values are stored internally in the range from -1.0 
to 1.0. This function allows a specific linear mapping of depth values to a 
normalized range of window z coordinates. The default range for window 
z values is 0 to 1 corresponding to the near and far clipping planes. 


Parameters: 

zNear GLclampd: A clamped value that represents the nearest possible window z 
value. 

zFar GLclampd: A clamped value that represents the largest possible window z 
value. 

Returns: None. 

See Also: glClearDepth, glDepthMask, glDepthFunc 

glDrawBuffer 

Purpose: Redirects OpenGL rendering to a specific color buffer. 

Include File: <gl.h> 

Syntax: 


void glDrawBuffer(GLenum mode) ; 


Description: By default, OpenGL renders to the back color buffer for double-buffered 
rendering contexts and to the front for single-buffered rendering 
contexts. This function allows you to direct OpenGL rendering to any 
available color buffer. Note that many implementations do not support 
left and right (stereo) or auxiliary color buffers. In the case of stereo 


Reference 


contexts, the modes that omit references to the left and right channels 

will render to both channels. For example, specifying GL_FRONT for a 

stereo context will actually render to both the left and right front buffers, 

and GL_FRONT_AND_BACK will render to up to four buffers simultaneously. 
Parameters: 


mode GLenum: A constant flag that specifies which color buffer should be the 
render target. Valid values for this parameter are listed in Table 3.3. 


TABLE 3.3 Color Buffer Destinations 


Constant Description 

GL_NONE Do not write anything to any color buffer. 

GL_FRONT_LEFT Write only to the front-left color buffer. 

GL_FRONT_RIGHT Write only to the front-right color buffer. 

GL_BACK_LEFT Write only to the back-left color buffer. 

GL_BACK_RIGHT Write only to the back-right color buffer. 

GL_FRONT Write only to the front color buffer. This is the default value for single- 
buffered rendering contexts. 

GL_BACK Write only to the back color buffer. This is the default value for double- 
buffered rendering contexts. 

GL_LEFT Write only to the left color buffer. 

GL_RIGHT Write only to the right color buffer. 

GL_FRONT_AND_BACK Write to both the front and back color buffers. 

GL_AUXi Write only to the auxiliary buffer j, with i being a value between 0 and 


GL_AUX_BUFFERS - 1. 


Returns: None. 

See Also: glClear, glColorMask 

glEdgeFlag 

Purpose: Flags polygon edges as either boundary or nonboundary edges. You can 


use this to determine whether interior surface lines are visible. 
Include File: <gl.h> 
Variations: 


void glEdgeFlag(GLboolean flag) ; 
void glEdgeFlagv(const GLboolean *flag); 


Description: When two or more polygons are joined to form a larger region, the edges 
on the outside define the boundary of the newly formed region. This 
function flags inside edges as nonboundary. This is used only when the 
polygon mode is set to either GL_LINE or GL_POINT. 
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Parameters: 
flag 

*flag 
Returns: 
See Also: 


glEnd 
Purpose: 
Include File: 
Syntax: 

void glEnd(); 


Description: 


Returns: 
See Also: 


glFrontFace 
Purpose: 
Include File: 
Syntax: 


GLboolean: Sets the edge flag to this value, True or False. 

const GLboolean *: A pointer to a value that is used for the edge flag. 
None. 

glBegin, glPolygonMode 


Terminates a list of vertices that specify a primitive initiated by glBegin. 
<gl.h> 


This function is used in conjunction with glBegin to delimit the vertices 
of an OpenGL primitive. You can include multiple vertices sets within a 
single glBegin/glEnd pair, as long as they are for the same primitive type. 
You can also make other settings with additional OpenGL commands 
that affect the vertices following them. You can call only these OpenGL 
functions within a g1Begin/glEnd sequence: glVertex, glColor, glIndex, 
glNormal, glEvalCoord, g1CallList, g1CallLists, glTexCoord, 
glEdgeFlag, and glMaterial. 


None. 
glBegin 


Defines which side of a polygon is the front or back. 
<gl.h> 


void glFrontFace(GLenum mode) ; 


Description: 


When a scene is made up of objects that are closed (you cannot see the 
inside), color or lighting calculations on the inside of the object are 
unnecessary. The gl1CullFace function turns off such calculations for 
either the front or back of polygons. The glFrontFace function deter- 
mines which side of the polygons is considered the front. If the vertices 
of a polygon as viewed from the front are specified so that they travel 
clockwise around the polygon, the polygon is said to have clockwise 
winding. If the vertices travel counterclockwise, the polygon is said to 
have counterclockwise winding. This function allows you to specify 


Reference 


either the clockwise or counterclockwise wound face to be the front of 


the polygon. 

Parameters: 

mode GLenum: Specifies the orientation of front-facing polygons: clockwise 
(GL_CW) or counterclockwise (GL_CCW). 

Returns: None. 

See Also: glCullFace, glLightModel, glPolygonMode, glMaterial 

glGetPolygonStipple 

Purpose: Returns the current polygon stipple pattern. 


Include File: <gl.h> 
Syntax: 
void glGetPolygonStipple(GLubyte *mask); 


Description: This function copies a 32-by-32-bit pattern that represents the polygon 
stipple pattern into a user-specified buffer. The pattern is copied to the 
memory location pointed to by mask. The packing of the pixels is affected 
by the last call to glPixelStore. 


Parameters: 

*mask GLubyte: A pointer to the place where the polygon stipple pattern is to be 
copied. 

Returns: None. 

See Also: glPolygonStipple, glLineStipple, glPixelStore 

glLineStipple 

Purpose: Specifies a line stipple pattern for line-based primitives GL_LINES, 
GL_LINE_STRIP, and GL_LINE_LOOP. 

Include File: <gl.h> 

Syntax: 


void glLineStipple(GLint factor, GLushort pattern); 


Description: This function uses the bit pattern to draw stippled (dotted and dashed) 
lines. The bit pattern begins with bit 0 (the rightmost bit), so the actual 
drawing pattern is the reverse of what is specified. The factor parameter 
is used to widen the number of pixels drawn or not drawn along the line 
specified by each bit in pattern. By default, each bit in the pattern speci- 
fies one pixel. To use line stippling, you must first enable stippling by 
calling 
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glEnable(GL_LINE_STIPPLE) ; 


Line stippling is disabled by default. If you are drawing multiple line 
segments, the pattern is reset for each new segment. That is, if a line 
segment is drawn such that it terminates halfway through the pattern, 
the next specified line segment is unaffected. 


Parameters: 

factor GLint: Specifies a multiplier that determines how many pixels will be 
affected by each bit in the pattern parameter. Thus, the pattern width is 
multiplied by this value. The default value is 1, and the maximum value 
is clamped to 255. 

pattern GLushort: Sets the 16-bit stippling pattern. The least significant bit (bit 0) 
is used first for the stippling pattern. The default pattern is all 1s. 

Returns: None. 

See Also: glPolygonStipple 

glLineWidth 

Purpose: Sets the width of lines drawn with GL_LINES, GL_LINE_STRIP, or 


GL_LINE_LOOP. 
Include File: <gl.h> 
Syntax: 
void glLineWidth(GLfloat width ); 


Description: This function sets the width in pixels of lines drawn with any of the line- 
based primitives. 


You can get the current line width setting by calling 
GLfloat fSize; 


glGetFloatv(GL_LINE_WIDTH, &fSize); 


The current line width setting will be returned in fSize. In addition, you 
can find the minimum and maximum supported line widths by calling 


GLfloat fSizes[2]; 
glGetFloatv(GL_LINE_WIDTH_RANGE, fSizes) ; 


In this instance, the minimum supported line width will be returned in 
fSizes[®], and the maximum supported width will be stored in 
fSizes[1]. Finally, you can find the smallest supported increment 
between line widths by calling 


Reference 


GLfloat fStepSize; 
glGetFloatv(GL_LINE_WIDTH_GRANULARITY ,&fStepSize) ; 
For any implementation of OpenGL, the only line width guaranteed to 


be supported is 1.0. For the Microsoft Windows generic implementation, 
the supported line widths range from 0.5 to 10.0, with a granularity of 


0.125. 

Parameters: 

width GLfloat: Sets the width of lines that are drawn with the line primitives. 
The default value is 1.0. 

Returns: None. 

See Also: glPointSize 

glPointSize 

Purpose: Sets the point size of points drawn with GL_POINTS. 


Include File: <gl.h> 
Syntax: 
void glPointSize(GLfloat size); 


Description: This function sets the diameter in pixels of points drawn with the 
GL_POINTS primitive. You can get the current pixel size setting by calling 


GLfloat fSize; 
glGetFloatv(GL_POINT SIZE, &fSize); 


The current pixel size setting will be returned in fSize. In addition, you 
can find the minimum and maximum supported pixel sizes by calling 


GLfloat fSizes[2]; 
glGetFloatv(GL_POINT_SIZE_RANGE, fSizes) ; 


In this instance, the minimum supported point size will be returned in 
fSizes[], and the maximum supported size will be stored in fSizes[1]. 
Finally, you can find the smallest supported increment between pixel 
sizes by calling 


GLfloat fStepSize; 


glGetFloatv(GL_POINT_SIZE_GRANULARITY , &fStepSize) ; 
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For any implementation of OpenGL, the only point size guaranteed to be 
supported is 1.0. For the Microsoft Windows generic implementation, the 
point sizes range from 0.5 to 10.0, with a granularity of 0.125. 


Parameters: 

size GLfloat: Sets the diameter of drawn points. The default value is 1.0. 
Returns: None. 

See Also: glLineWidth 

glPolygonMode 

Purpose: Sets the rasterization mode used to draw polygons. 


Include File: <gl.h> 
Syntax: 
void glPolygonMode(GLenum face, GLenum mode) ; 


Description: This function allows you to change how polygons are rendered. By 
default, polygons are filled or shaded with the current color or material 
properties. However, you may also specify that only the outlines or only 
the vertices are drawn. Furthermore, you may apply this specification to 
the front, back, or both sides of polygons. 


Parameters: 

face GLenum: Specifies which face of polygons is affected by the mode change: 
GL_FRONT, GL_BACK, or GL_FRONT_AND_BACK. 

mode GLenum: Specifies the new drawing mode. GL_FILL is the default, produc- 


ing filled polygons. GL_LINE produces polygon outlines, and GL_POINT 
plots only the points of the vertices. The lines and points drawn by 
GL_LINE and GL_POINT are affected by the edge flag set by glEdgeFlag. 


Returns: None. 


See Also: glEdgeFlag, glLineStipple, glLineWidth, glPointSize, 
glPolygonStipple 

glPolygonOffset 

Purpose: Sets the scale and units used to calculate depth values. 

Include File: <gl.h> 

Syntax: 


void glPolygonOffset(GLfloat factor, GLfloat units) ; 


Description: 


Reference 


This function allows you to add or subtract an offset to a fragment’s 
calculated depth value. The amount of offset is calculated by the follow- 
ing formula: 


offset = (m * factor) + (r * units) 


The value of m is calculated by OpenGL and represents the maximum 
depth slope of the polygon. The r value is the minimum value that will 
create a resolvable difference in the depth buffer, and is implementation 
dependent. Polygon offset applies only to polygons but affects lines and 
points when rendered as a result of a call to glPolygonMode. You enable 
or disable the offset value for each mode by using glEnable/glDisable 
with GL_POLYGON_OFFSET_FILL, GL_POLYGON_OFFSET_LINE, or 
GL_POLYGON_OFFSET_POINT. 


Parameters: 

factor GLfloat: Scaling factor used to create a depth buffer offset for each 
polygon. Zero by default. 

units GLfloat: Value multiplied by an implementation-specific value to create a 
depth offset. Zero by default. 

Returns: None. 

See Also: glDepthFunc, glDepthRange, glPolygonMode 

glPolygonStipple 

Purpose: Sets the pattern used for polygon stippling. 


Include File: 
Syntax: 


<gl.h> 


void glPolygonStipple(const GLubyte *mask ); 


Description: 


Parameters: 
*mask 


Returns: 
See Also: 


You can use a 32-by-32-bit stipple pattern for filled polygons by using 
this function and enabling polygon stippling by calling 
glEnable(GL_POLYGON_STIPPLE). The 1s in the stipple pattern are filled 
with the current color, and Os are not drawn. 


const GLubyte: Points to a 32-by-32-bit storage area that contains the 
stipple pattern. The packing of bits within this storage area is affected by 
glPixelStore. By default, the MSB (most significant bit) is read first 
when determining the pattern. 

None. 


glLineStipple, glGetPolygonStipple, glPixelStore 
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glScissor 

Purpose: Defines a scissor box in window coordinates outside of which no drawing 
occurs. 

Include File: <gl.h> 

Syntax: 

void glScissor(GLint x, GLint y, GLint width, GLint height); 


Description: This function defines a rectangle in window coordinates called the scissor 
box. When the scissor test is enabled with glEnable(GL_SCISSOR_TEST), 
OpenGL drawing commands and buffer operations occur only within the 
scissor box. 


Parameters: 

xy GLint: The lower-left corner of the scissor box, in window coordinates. 
width GLint: The width of the scissor box in pixels. 

height GLint: The height of the scissor box in pixels. 

Returns: None. 

See Also: glStencilFunc, glStencil0p 

glStencilFunc 

Purpose: Sets the comparison function, reference value, and mask for a stencil test. 
Include File: <gl.h> 

Syntax: 


void glStencilFunc(GLenum func, GLint ref, GLuint mask); 


Description: When the stencil test is enabled using gl1Enable(GL_STENCIL_TEST), the 
stencil function is used to determine whether a color fragment should be 
discarded or kept (drawn). The value in the stencil buffer is compared to 
the reference value ref, using the comparison function specified by func. 
Both the reference value and stencil buffer value may be bitwise ANDed 
with the mask. Valid comparison functions are given in Table 3.4. The 
result of the stencil test also causes the stencil buffer to be modified 
according to the behavior specified in the function g1StencilOp. 


Parameters: 
func GLenum: Stencil comparison function. Valid values are listed in Table 3.4. 
ref GLint: Reference value against which the stencil buffer value is 


compared. 


Reference 


mask GLuint: Binary mask value applied to both the reference and stencil 
buffer values. 


TABLE 3.4 Stencil Test Comparison Functions 


Constant Meaning 
GL_NEVER Never pass the stencil test. 
GL_ALWAYS Always pass the stencil test. 
GL_LESS Pass only if the reference value is less than the stencil buffer value. 
GL_LEQUAL Pass only if the reference value is less than or equal to the stencil buffer value. 
GL_EQUAL Pass only if the reference value is equal to the stencil buffer value. 
GL_GEQUAL Pass only if the reference value is greater than or equal to the stencil buffer value. 
GL_GREATER Pass only if the reference value is greater than the stencil buffer value. 
GL_NOTEQUAL Pass only if the reference value is not equal to the stencil buffer value. 
Returns: None. 
See Also: glStencil0p, glClearStencil 
glStencilMask 
Purpose: Selectively allows or disallows changes to the stencil buffer. 


Include File: <gl.h> 
Syntax: 
void glStencilMask(GLboolean flag); 


Description: If a stencil buffer is created for an OpenGL rendering context, OpenGL 
will calculate, store, and make use of stencil values when stenciling is 
enabled. When the stencil test is disabled, values are still calculated and 
stored in the stencil buffer. This function allows you to selectively enable 
and disable writing to the stencil buffer. 


Parameters: 

flag GLboolean: When this parameter is set to GL_TRUE, stencil buffer writes 
are enabled (default). Setting this parameter to GL_FALSE disables changes 
to the depth buffer. 

Returns: None. 

See Also: glStencilop, glClearStencil, glStencilMask 

glStencilOp 

Purpose: Specifies what action to take in regards to the stored value in the stencil 


buffer for a rendered fragment. 
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Include File: 
Syntax: 


<gl.h> 


void glStencil0p(GLenum sfail, GLenum zfail, GLenum zpass) ; 


Description: 


Parameters: 
sfail 
zfail 


zPass 


This function describes what action to take when a fragment fails the 
stencil test. Even when fragments do not pass the stencil test and are not 
produced in the color buffer, the stencil buffer can still be modified by 
setting the appropriate action for the sfail parameter. In addition, even 
when the stencil test passes, the zfail and zpass parameters describe the 
desired action based on that fragment’s depth buffer test. The valid 
actions and their constants are given in Table 3.5. 


GLenum: Operation to perform when the stencil test fails. 
GLenum: Operation to perform when the depth test fails. 
GLenum: Operation to perform when the depth test passes. 


TABLE 3.5 Stencil Operation Constants 


Constant 


GL_KEEP 
GL_ZERO 
GL_REPLACE 


GL_INCR 
GL_DECR 
GL_INVERT 


GL_INCR_WRAP 


GL_DECR_WRAP 


Returns: 
See Also: 


glVertex 


Purpose: 
Include File: 


Description 


Keep the current stencil buffer value. 

Set the current stencil buffer value to 0. 

Replace the stencil buffer value with the reference value specified in 
glStencilFunc. 

Increment the stencil buffer value. Clamped to the bit range of the stencil buffer. 
Decrement the stencil buffer value. Clamped to the bit range of the stencil buffer. 
Bitwise-invert the current stencil buffer value. 

Increment the current stencil buffer value. When the maximum representable value 
for the given stencil buffer’s bit depth is reached, the value wraps back to 0. 
Decrement the current stencil buffer value. When the value is decremented below 
0, the stencil buffer value wraps to the highest possible positive representation for 
its bit depth. 


None. 


glStencilFunc, glClearStencil 


Specifies the 3D coordinates of a vertex. 
<gl.h> 


Variations: 


void 
void 
void 
void 
void 


glVertex2d(GLdouble x, GLdouble y); 
glVertex2f(GLfloat x, GLfloat y); 
glVertex2i(GLint x, GLint y); 
glVertex2s(GLshort x, GLshort y); 
glVertex3d(GLdouble x, GLdouble y, GLdouble z); 


Reference 


void glVertex3f(GLfloat x, GLfloat y, GLfloat z); 

void glVertex3i(GLint x, GLint y, GLint z); 

void glVertex3s(GLshort x, GLshort y, GLshort z); 

void glVertex4d(GLdouble x, GLdouble y, GLdouble z, Gldouble w); 

void glVertex4f(GLfloat x, GLfloat y, GLfloat z, GLfloat w); 

void glVertex4i(GLint x, GLint y, GLint z, GLint w); 

void glVertex4s(GLshort x, GLshort y, GLshort z, GLshort w); 

void glVertex2dv(const GLdouble *v); 

void glVertex2fv(const GLfloat *v); 

void glVertex2iv(const GLint *v); 

void glVertex2sv(const GLshort *v); 

void glVertex3dv(const GLdouble *v); 

void glVertex3fv(const GLfloat *v); 

void glVertex3iv(const GLint *v); 

void glVertex3sv(const GLshort *v); 

void glVertex4dv(const GLdouble *v); 

void glVertex4fv(const GLfloat *v); 

void glVertex4iv(const GLint *v); 

void glVertex4sv(const GLshort *v); 

Description: This function is used to specify the vertex coordinates of the points, 
lines, and polygons specified by a previous call to g1Begin. You cannot 
call this function outside the scope of a g1Begin/glEnd pair. 

Parameters: 

Xi Vaz The x, y, and z coordinates of the vertex. When z is not specified, the 
default value is 0.0. 

w The w coordinate of the vertex. This coordinate is used for scaling 
purposes and by default is set to 1.0. Scaling occurs by dividing the other 
three coordinates by this value. 

*V An array of values that contain the two, three, or four values needed to 
specify the vertex. 

Returns: None. 

See Also: glBegin, glEnd 


157 


ee 


ade 2 ae yer 


wie se) eohielts on fun op gti Ai cy 


a eid, 


ie Jers 1 


sa@yot 

“yf Tale 

WORE Go LOG 
(8? GROTLE \s Shit 
ee at 2 ' 


S ats ws, SO 


{ iggh Ges Wha Uiy 


wary @ oh ite: RHE & +0 SG 
" ge Teerigehin & hs Se Pe 


inchs ae! Fv  Otu 


bere. oath ay 


ibtci oe 


= yt) trad git (ie a! see i) 


st) iy 


Seg Pap ov pe 


eee we 
. 


i AD) ete 


ve ‘ wit .Sa @ 
TOMAD. eee Ca 


F ‘iW yar ct 


a 6@ rl? oF ont? | 1g 


was 2 Teele 


ac IE LOLS 9e Bae ~ 
y TUR, > “aes 
> 
(Pai. ‘» WE st, 
© 6700 ca. telesc)  * 
ee ee ea 


JS a “nee 


pe? TOES /OroSe 
4 Re TAaus 
1a or Peneiiey ee 7 
fe ego 
w Ohi Se Fem} © 
7% A. © aR ver 


* eg Tenaya? 


uta Laney V8 
(o® Yel sri jae 
vg SK pe Se 


ff Oat DESI) aT! 
(ove ey [aA Pi 


=AHathiepe @PT rey 
vee Bie gua tl) 
7 6 eid? Agee 
ly panies v0 IT 


heer, Gl fiery: enuceeyay 


2 LJetiso sant: 


‘tat pa 
i) af Wile! 


Ahh het 


iy ~ieyedie 


wtetie pr 


ey) eRe? © . im, 


_ ivf; = LAY 
‘S tea *: A 
Wart: 


sg?* wis 


welt Wiese Wier 


ri isefig “ocr 
Ayo fy 
bes pap hs 


ive F 


LY fe! 


+ “Saag a? 


Tot 
Cie a 
4 Wee # 
im SESE) whee 
j AW i 
¥ 
onl,» i. 
? ee rie 
er vis a; 


aimee at 


=e wa 
eh oak 


CHAPTER 4 


Geometric Transformations: The 
Pipeline 


by Richard S. Wright, Jr. 


WHAT YOU’LL LEARN IN THIS CHAPTER: 


How To Functions You'll Use 
Establish your position in the scene gluLookAt 

Position objects within the scene glTranslate/glRotate 

Scale objects glScale 

Establish a perspective transformation gluPerspective 

Perform your own matrix transformations glLoadMatrix/g1MultMatrix 
Use a camera to move around in a scene gluLookAt 


In Chapter 3, “Drawing in Space: Geometric Primitives and Buffers,” you learned how to 
draw points, lines, and various primitives in 3D. To turn a collection of shapes into a 
coherent scene, you must arrange them in relation to one another and to the viewer. In 
this chapter, you start moving shapes and objects around in your coordinate system. 
(Actually, you don’t move the objects, but rather shift the coordinate system to create the 
view you want.) The ability to place and orient your objects in a scene is a crucial tool for 
any 3D graphics programmer. As you will see, it is actually convenient to describe your 
objects’ dimensions around the origin and then transform the objects into the desired posi- 
tion. 


Is This the Dreaded Math Chapter? 


In most books on 3D graphics programming, yes, this would be the dreaded math chapter. 
However, you can relax; we take a more moderate approach to these principles than some 
texts. 
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The keys to object and coordinate transformations are two matrices maintained by 
OpenGL. To familiarize you with these matrices, this chapter strikes a compromise 
between two extremes in computer graphics philosophy. On one hand, we could warn 
you, “Please review a textbook on linear algebra before reading this chapter.” On the other 
hand, we could perpetuate the deceptive reassurance that you can “learn to do 3D graph- 
ics without all those complex mathematical formulas.” But we don’t agree with either 
camp. 


In reality, you can get along just fine without understanding the finer mathematics of 3D 
graphics, just as you can drive your car every day without having to know anything at all 
about automotive mechanics and the internal combustion engine. But you had better 
know enough about your car to realize that you need an oil change every so often, that 
you have to fill the tank with gas regularly, and that you must change the tires when they 
get bald. This knowledge makes you a responsible (and safe!) automobile owner. If you 
want to be a responsible and capable OpenGL programmer, the same standards apply. You 
need to understand at least the basics so you know what can be done and what tools best 
suit the job. If you are a beginner, you will find that, with some practice, matrix math and 
vectors will gradually make more and more sense, and you will develop a more intuitive 
(and powerful) ability to make full use of the concepts we introduce in this chapter. 


So, even if you don’t already have the ability to multiply two matrices in your head, you 
need to know what matrices are and that they are the means to OpenGL’s 3D magic. But 
before you go dusting off that old linear algebra textbook (doesn’t everyone have one?), 
have no fear: OpenGL does all the math for you. Think of using OpenGL as using a calcu- 
lator to do long division when you don’t know how to do it on paper. Although you don’t 
have to do it yourself, you still know what it is and how to apply it. See—you can eat your 
cake and have it, too! 


Understanding Transformations 


If you think about it, most 3D graphics aren’t really 3D. We use 3D concepts and termi- 
nology to describe what something looks like; then this 3D data is “squished” onto a 2D 
computer screen. We call the process of squishing 3D data down into 2D data projection, 
and we introduced both orthographic and perspective projections back in Chapter 1, 
“Introduction to 3D Graphics and OpenGL.” We refer to the projection whenever we want 
to describe the type of transformation (orthographic or perspective) that occurs during 
projection, but projection is only one of the different types of transformations that occurs 
in OpenGL. Transformations also allow you to rotate objects around; move them about; 
and even stretch, shrink, and warp them. 


Three types of geometric transformations occur between the time you specify your vertices 
and the time they appear on the screen: viewing, modeling, and projection. In this 
section, we examine the principles of each type of transformation, which are summarized 
in Table 4.1. 
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TABLE 4.1. Summary of the OpenGL Transformation Terminology 


Transformation Use 

Viewing Specifies the location of the viewer or camera 

Modeling Moves objects around the scene 

Modelview Describes the duality of viewing and modeling transformations 
Projection Clips and sizes the viewing volume 

Viewport A pseudo-transformation that scales the final output to the window 


Eye Coordinates 


An important concept throughout this chapter is that of eye coordinates. Eye coordinates 
are from the viewpoint of the observer, regardless of any transformations that may occur; 
you can think of them as “absolute” screen coordinates. Thus, eye coordinates are not real 
coordinates; instead, they represent a virtual fixed coordinate system that is used as a 
common frame of reference. All the transformations discussed in this chapter are 
described in terms of their effects relative to the eye coordinate system. 


Figure 4.1 shows the eye coordinate system from two viewpoints. On the left (a), the eye 
coordinates are represented as seen by the observer of the scene (that is, perpendicular to 
the monitor). On the right (b), the eye coordinate system is rotated slightly so you can 
better see the relation of the z-axis. Positive x and y are pointed right and up, respectively, 
from the viewer's perspective. Positive z travels away from the origin toward the user, and 
negative z values travel farther away from the viewpoint into the screen. 
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FIGURE 4.1 Two perspectives of eye coordinates. 
When you draw in 3D with OpenGL, you use the Cartesian coordinate system. In the 


absence of any transformations, the system in use is identical to the eye coordinate system 
just described. 


161 


162 


CHAPTER 4 Geometric Transformations: The Pipeline 


Viewing Transformations 


The viewing transformation is the first to be applied to your scene. It is used to determine 
the vantage point of the scene. By default, the point of observation in a perspective 
projection is at the origin (0,0,0) looking down the negative z-axis (“into” the monitor 
screen). This point of observation is moved relative to the eye coordinate system to 
provide a specific vantage point. When the point of observation is located at the origin, 
objects drawn with positive z values are behind the observer. 


The viewing transformation allows you to place the point of observation anywhere you 
want and look in any direction. Determining the viewing transformation is like placing 
and pointing a camera at the scene. 


In the grand scheme of things, you must specify the viewing transformation before any 
other transformations. The reason is that it appears to move the current working coordi- 
nate system in respect to the eye coordinate system. All subsequent transformations then 
occur based on the newly modified coordinate system. Later, you’ll see more easily how 
this works, when we actually start looking at how to make these transformations. 


Modeling Transformations 


Modeling transformations are used to manipulate your model and the particular objects 
within it. These transformations move objects into place, rotate them, and scale them. 
Figure 4.2 illustrates three of the most common modeling transformations that you will 
apply to your objects. Figure 4.2a shows translation, where an object is moved along a 
given axis. Figure 4.2b shows a rotation, where an object is rotated about one of the axes. 
Finally, Figure 4.2c shows the effects of scaling, where the dimensions of the object are 
increased or decreased by a specified amount. Scaling can occur nonuniformly (the various 
dimensions can be scaled by different amounts), so you can use scaling to stretch and 
shrink objects. 


The final appearance of your scene or object can depend greatly on the order in which the 
modeling transformations are applied. This is particularly true of translation and rotation. 
Figure 4.3a shows the progression of a square rotated first about the z-axis and then trans- 
lated down the newly transformed x-axis. In Figure 4.3b, the same square is first translated 
down the x-axis and then rotated around the z-axis. The difference in the final disposi- 
tions of the square occurs because each transformation is performed with respect to the 
last transformation performed. In Figure 4.3a, the square is rotated with respect to the 
origin first. In 4.3b, after the square is translated, the rotation is performed around the 
newly translated origin. 
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FIGURE 4.2 The modeling transformations. 


The Modelview Duality 


The viewing and modeling transformations are, in fact, the same in terms of their internal 
effects as well as their effects on the final appearance of the scene. The distinction 
between the two is made purely as a convenience for the programmer. There is no real 
difference between moving an object backward and moving the reference system forward; 
as shown in Figure 4.4, the net effect is the same. (You experience this effect firsthand 
when you're sitting in your car at an intersection and you see the car next to you roll 
forward; it might seem to you that your own car is rolling backward.) The term modelview 
indicates that you can think of this transformation either as the modeling transformation 
or the viewing transformation, but in fact there is no distinction; thus, it is the modelview 
transformation. 
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system is now rotated 
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FIGURE 4.3 Modeling transformations: rotation/translation and translation/rotation. 


Moving the observer 
(a) 


FIGURE 4.4 Two ways of looking at the viewing transformation. 


The viewing transformation, therefore, is essentially nothing but a modeling transforma- 
tion that you apply to a virtual object (the viewer) before drawing objects. As you will 
soon see, new transformations are repeatedly specified as you place more objects in the 
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scene. By convention, the initial transformation provides a reference from which all other 
transformations are based. 


Projection Transformations 


The projection transformation is applied to your vertices after the modelview transforma- 
tion. This projection actually defines the viewing volume and establishes clipping planes. 
The clipping planes are plane equations in 3D space that OpenGL uses to determine 
whether geometry can be seen by the viewer.. More specifically, the projection transforma- 
tion specifies how a finished scene (after all the modeling is done) is projected to the final 
image on the screen. You learn about two types of projections in this chapter: ortho- 
graphic and perspective. 


In an orthographic, or parallel, projection, all the polygons are drawn onscreen with exactly 
the relative dimensions specified. Lines and polygons are mapped directly to the 2D screen 
using parallel lines, which means no matter how far away something is, it is still drawn 
the same size, just flattened against the screen. This type of projection is typically used for 
CAD or for rendering two-dimensional images such as blueprints or two-dimensional 
graphics such as text or onscreen menus. 


A perspective projection shows scenes more as they appear in real life instead of as a blue- 
print. The trademark of perspective projections is foreshortening, which makes distant 
objects appear smaller than nearby objects of the same size. Lines in 3D space that might 
be parallel do not always appear parallel to the viewer. With a railroad track, for instance, 
the rails are parallel, but using perspective projection, they appear to converge at some 
distant point. 


The benefit of perspective projection is that you don’t have to figure out where lines 
converge or how much smaller distant objects are. All you need to do is specify the scene 
using the modelview transformations and then apply the perspective projection. OpenGL 
works all the magic for you. Figure 4.5 compares orthographic and perspective projections 
on two different scenes. 


Everything same size 


FIGURE 4.5 Side-by-side example of an orthographic versus perspective projection. 
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Orthographic projections are used most often for 2D drawing purposes where you want an 
exact correspondence between pixels and drawing units. You might use them for a 
schematic layout, text, or perhaps a 2D graphing application. You also can use an ortho- 
graphic projection for 3D renderings when the depth of the rendering has a very small 
depth in comparison to the distance from the viewpoint. Perspective projections are used 
for rendering scenes that contain wide open spaces or objects that need to have the fore- 
shortening applied. For the most part, perspective projections are typical for 3D graphics. 
In fact, looking at a 3D object with an orthographic projection can be somewhat unset- 
tling. 


Viewport Transformations 


When all is said and done, you end up with a two-dimensional projection of your scene 
that will be mapped to a window somewhere on your screen. This mapping to physical 
window coordinates is the last transformation that is done, and it is called the viewport 
transformation. Usually, a one-to-one correspondence exists between the color buffer and 
window pixels, but this is not always strictly the case. In some circumstances, the viewport 
transformation remaps what are called “normalized” device coordinates to window coordi- 
nates. Fortunately, this is something you don’t need to worry about. 


The Matrix: Mathematical Currency for 3D Graphics 


Now that you’re armed with some basic vocabulary and definitions of transformations, 
you’re ready for some simple matrix mathematics. Let’s examine how OpenGL performs 
these transformations and get to know the functions you call to achieve the desired 
effects. 


The mathematics behind these transformations are greatly simplified by the mathematical 
notation of the matrix. You can achieve each of the transformations we have discussed by 
multiplying a matrix that contains the vertices (usually, this is a simple vector) by a matrix 
that describes the transformation. Thus, all the transformations achievable with OpenGL 
can be described as the product of two or more matrix multiplications. 


What Is a Matrix? 


The Matrix is not only a wildly popular Hollywood movie trilogy, but an exceptionally 
powerful mathematical tool that greatly simplifies the process of solving one or more 
equations with variables that have complex relationships to one another. One common 
example of this, near and dear to the hearts of graphics programmers, is coordinate trans- 
formations. For example, if you have a point in space represented by x, y, and z coordi- 
nates, and you need to know where that point is if you rotate it some number of degrees 
around some arbitrary point and orientation, you would use a matrix. Why? Because the 
new x coordinate depends not only on the old x coordinate and the other rotation para- 
meters, but also on what the y and z coordinates were as well. This kind of dependency 
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between the variables and solution is just the sort of problem that matrices excel at. For 
fans of the Matrix movies who have a mathematical inclination, the term matrix is indeed 
an appropriate title. 


Mathematically, a matrix is nothing more than a set of numbers arranged in uniform rows 
and columns—in programming terms, a two-dimensional array. A matrix doesn’t have to 
be square, but each row or column must have the same number of elements as every other 
row or column in the matrix. Figure 4.6 presents some examples of matrices. They don’t 
represent anything in particular, but serve only to demonstrate matrix structure. Note that 
it is also valid for a matrix to have a single column or row. A single row or column of 
numbers is also more simply called a vector, and vectors also have some interesting and 
useful applications all their own. 


ae, ae. 0 42 
ee ae 1.5 0.877 
a ee oe 2 14 


won 


FIGURE 4.6 Three examples of matrices. 


Matrix and vector are two important terms that you will see often in 3D graphics program- 
ming literature. When dealing with these quantities, you will also see the term scalar. A 
scalar is just an ordinary single number used to represent magnitude or a specific quantity 
(you know—a regular old plain simple number...like before you cared or had all this 
jargon added to your vocabulary). 


Matrices can be multiplied and added together, but they can also be multiplied by vectors 
and scalar values. Multiplying a point (a vector) by a matrix (a transformation) yields a 
new transformed point (a vector). Matrix transformations are actually not too difficult to 
understand but can be intimidating at first. Because an understanding of matrix transfor- 
mations is fundamental to many 3D tasks, you should still make an attempt to become 
familiar with them. Fortunately, only a little understanding is enough to get you going 
and doing some pretty incredible things with OpenGL. Over time, and with a little more 
practice and study (see Appendix A, “Further Reading”), you will master this mathematical 
tool yourself. In the meantime, you can find a number of useful matrix and vector func- 
tions and features available, with source code, in the glTools library (see the \common 
directory under the samples directory) on the CD that accompanies this book. 


The Transformation Pipeline 


To effect the types of transformations described in this chapter, you modify two matrices 
in particular: the modelview matrix and projection matrix. Don’t worry; OpenGL provides 
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some high-level functions that you can call for these transformations. After you’ve 
mastered the basics of the OpenGL API, you will undoubtedly start trying some of the 
more advanced 3D rendering techniques. Only then will you need to call the lower-level 
functions that actually set the values contained in the matrices. 


The road from raw vertex data to screen coordinates is a long one. Figure 4.7 provides a 
flowchart of this process. First, your vertex is converted to a 1x4 matrix in which the first 
three values are the x, y, and z coordinates. The fourth number is a scaling factor that you 
can apply manually by using the vertex functions that take four values. This is the w coor- 
dinate, usually 1.0 by default. You will seldom modify this value directly. 


Xo Xx X, 

Yo Modelview ¥. Projection wi 
matrix matrix |~~ | division [—>|¥/Me}—> ++ 

1 Z, Z, 1/W, 

Wo Ww oe W 

Original Transformed Clip Normalized 
vertex data eye coordinates coordinates device coordinates 

Viewport 


** —>* | transformation | — 
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FIGURE 4.7 The vertex transformation pipeline. 


Window coordinates 


The vertex is then multiplied by the modelview matrix, which yields the transformed eye 
coordinates. The eye coordinates are then multiplied by the projection matrix to yield clip 
coordinates. This effectively eliminates all data outside the viewing volume. The clip coor- 
dinates are then divided by the w coordinate to yield normalized device coordinates. The 
w value may have been modified by the projection matrix or the modelview matrix, 
depending on the transformations that occurred. Again, OpenGL and the high-level 
matrix functions hide this process from you. 


Finally, your coordinate triplet is mapped to a 2D plane by the viewport transformation. 


The Modelview Matrix 


The modelview matrix is a 4x4 matrix that represents the transformed coordinate system 
you are using to place and orient your objects. The vertices you provide for your primitives 
are used as a single-column matrix and multiplied by the modelview matrix to yield new 
transformed coordinates in relation to the eye coordinate system. 
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In Figure 4.8, a matrix containing data for a single vertex is multiplied by the modelview 
matrix to yield new eye coordinates. The vertex data is actually four elements with an 
extra value, w, that represents a scaling factor. This value is set by default to 1.0, and rarely 
will you change it yourself. 


prea 4 tf Lhe J 


FIGURE 4.8 Matrix equation that applies the modelview transformation to a single vertex. 


Translation 
Let’s consider an example that modifies the modelview matrix. Say you want to draw a 
cube using the GLUT library’s glutWireCube function. You simply call 


glutWireCube(10.0f); 


A cube that measures 10 units on a side is then centered at the origin. To move the cube 
up the y-axis by 10 units before drawing it, you multiply the modelview matrix by a 
matrix that describes a translation of 10 units up the y-axis and then do your drawing. In 
skeleton form, the code looks like this: 


// Construct a translation matrix for positive 10 Y 
// Multiply it by the modelview matrix 


// Draw the cube 
glutWireCube(10.0f); 


Actually, such a matrix is fairly easy to construct, but it requires quite a few lines of code. 
Fortunately, OpenGL provides a high-level function that performs this task for you: 

void glTranslatef(GLfloat x, GLfloat y, GLfloat z); 

This function takes as parameters the amount to translate along the x, y, and z directions. 


It then constructs an appropriate matrix and does the multiplication. The pseudocode 
looks like the following, and the effect is illustrated in Figure 4.9: 


// Translate up the y-axis 10 units 
glTranslatef(0.0f, 10.0f, 0.0f); 


// Draw the cube 
glutWireCube(10.0f) ; 
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FIGURE 4.9 A cube translated 10 units in the positive y direction. 


IS TRANSLATION ALWAYS A MATRIX OPERATION? 


The studious reader may note that translations do not always require a full matrix multiplication, 
but can be simplified with a simple scalar addition to the vertex position. However, for more 
complex transformations that include combined simultaneous operations, it is correct to describe 
translation as a matrix operation. Fortunately, if you let OpenGL do the heavy lifting for you, such 
as we have done here, the implementation can usually figure out the optimum method to use. 


Rotation 
To rotate an object about one of the three coordinate axes, or indeed any arbitrary vector, 
you have to devise a rotation matrix. Again, a high-level function comes to the rescue: 


glRotatef(GLfloat angle, GLfloat x, GLfloat y, GLfloat z); 


Here, we perform a rotation around the vector specified by the x, y, and z arguments. The 
angle of rotation is in the counterclockwise direction measured in degrees and specified by 
the argument angle. In the simplest of cases, the rotation is around only one of the axes. 


You can also perform a rotation around an arbitrary axis by specifying x, y, and z values 
for that vector. To see the axis of rotation, you can just draw a line from the origin to the 
point represented by (x,y,z). The following code rotates the cube by 45° around an arbi- 
trary axis specified by (1,1,1), as illustrated in Figure 4.10: 


// Perform the transformation 
glRotatef(45.0f, 1.0f, 1.0f, 1.0f); 


// Draw the cube 
glutWireCube(10.0f) ; 


The Matrix: Mathematical Currency for 3D Graphics 


Zz 


FIGURE 4.10 A cube rotated about an arbitrary axis. 


Scaling 
A scaling transformation increases the size of your object by expanding all the vertices 
along the three axes by the factors specified. The function 


glScalef(GLfloat x, GLfloat y, GLfloat z); 


multiplies the x, y, and z values by the scaling factors specified. 


Scaling does not have to be uniform, and you can use it to both stretch or squeeze objects 
along different directions. For example, the following code produces a cube that is twice as 
large along the x- and z-axes as the cubes discussed in the previous examples, but still the 

same along the y-axis. The result is shown in Figure 4.11. 


// Perform the scaling transformation 
glScalef(2.0f, 1.0f, 2.0f); 


// Draw the cube 
glutWireCube(10.0f) ; 


z 


FIGURE 4.11 A nonuniform scaling of a cube. 
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The Identity Matrix 


About now, you might be wondering why we had to bother with all this matrix stuff in 
the first place. Can’t we just call these transformation functions to move our objects 
around and be done with it? Do we really need to know that it is the modelview matrix 
that is modified? 


The answer is yes and no (but it’s no only if you are drawing a single object in your 
scene). The reason is that the effects of these functions are cumulative. Each time you call 
one, the appropriate matrix is constructed and multiplied by the current modelview 
matrix. The new matrix then becomes the current modelview matrix, which is then multi- 
plied by the next transformation, and so on. 


Suppose you want to draw two spheres—one 10 units up the positive y-axis and one 10 
units out the positive x-axis, as shown in Figure 4.12. You might be tempted to write code 
that looks something like this: 


// Go 10 units up the y-axis 
glTranslatef(0.0f, 10.0f, 0.0f); 


// Draw the first sphere 
glutSolidSphere(1.0f,15,15); 


// Go 10 units out the x-axis 
glTranslatef(10.0f, 0.0f, 0.0f); 


// Draw the second sphere 
glutSolidSphere(1.0f) ; 
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FIGURE 4.12 Two spheres drawn on the y- and x-axes. 
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Consider, however, that each call to glTranslate is cumulative on the modelview matrix, 
so the second call translates 10 units in the positive x direction from the previous transla- 
tion in the y direction. This yields the results shown in Figure 4.13. 


1 


FIGURE 4.13 The result of two consecutive translations. 


You can make an extra call to glTranslate to back down the y-axis 10 units in the nega- 
tive direction, but this makes some complex scenes difficult to code and debug—not to 
mention that you throw extra transformation math at the CPU. A simpler method is to 
reset the modelview matrix to a known state—in this case, centered at the origin of the 
eye coordinate system. 


You reset the origin by loading the modelview matrix with the identity matrix. The identity 
matrix specifies that no transformation is to occur, in effect saying that all the coordinates 
you specify when drawing are in eye coordinates. An identity matrix contains all Os, with 
the exception of a diagonal row of 1s. When this matrix is multiplied by any vertex 
matrix, the result is that the vertex matrix is unchanged. Figure 4.14 shows this equation. 
Later in the chapter, we discuss in more detail why these numbers are where they are. 


10 0 0 0 
[ 8045 -20 1.0 ] : e i : = [ 8045 -20 10 ] 
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FIGURE 4.14 Multiplying a vertex by the identity matrix yields the same vertex matrix. 


As we've already stated, the details of performing matrix multiplication are outside the 
scope of this book. For now, just remember this: Loading the identity matrix means that 
no transformations are performed on the vertices. In essence, you are resetting the 
modelview matrix back to the origin. 
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The following two lines load the identity matrix into the modelview matrix: 


glMatrixMode (GL_MODELVIEW) ; 
glLoadidentity(); 


The first line specifies that the current operating matrix is the modelview matrix. After 
you set the current operating matrix (the matrix that your matrix functions are affecting), 
it remains the active matrix until you change it. The second line loads the current matrix 
(in this case, the modelview matrix) with the identity matrix. 


Now, the following code produces results as shown earlier in Figure 4.12: 


// Set current matrix to modelview and reset 
glMatrixMode(GL_MODELVIEW) ; 
glLoadIdentity(); 


// Go 10 units up the y-axis 
glTranslatef(0.0f, 10.0f, 0.0f); 


// Draw the first sphere 
glutSolidSphere(1.0f, 15, 15); 


// Reset modelview matrix again 
glLoadidentity(); 


// Go 10 units out the x-axis 
glTranslatef(10.0f, 0.0f, 0.0f); 


// Draw the second sphere 
glutSolidSphere(1.0f, 15, 15); 


The Matrix Stacks 


Resetting the modelview matrix to identity before placing every object is not always desir- 
able. Often, you want to save the current transformation state and then restore it after 
some objects have been placed. This approach is most convenient when you have initially 
transformed the modelview matrix as your viewing transformation (and thus are no 
longer located at the origin). 


To facilitate this procedure, OpenGL maintains a matrix stack for both the modelview and 
projection matrices. A matrix stack works just like an ordinary program stack. You can 
push the current matrix onto the stack to save it and then make your changes to the 
current matrix. Popping the matrix off the stack restores it. Figure 4.15 shows the stack 
principle in action. 


175 


FIGURE 4.15 The matrix stack in action. 


TEXTURE MATRIX STACK 


The texture stack is another matrix stack available to you. You use it to transform texture coordi- 
nates. Chapter 8, “Texture Mapping: The Basics,” examines texture mapping and texture coordi- 
nates and contains a discussion of the texture matrix stack. 


The stack depth can reach a maximum value that you can retrieve with a call to either 


glGet (GL_MAX_MODELVIEW_STACK_DEPTH) ; 


or 


glGet (GL_MAX_PROJECTION_STACK_DEPTH) ; 


If you exceed the stack depth, you get a GL_STACK_OVERFLOW error; if you try to pop a 
matrix value off the stack when there is none, you generate a OW errorGL_STACK_UNDERFLOW 
error. The stack depth is implementation dependent. For the Microsoft software imple- 
mentation, the values are 32 for the modelview and 2 for the projection stack. 


A Nuclear Example 


Let’s put to use what we have learned. In the next example, we build a crude, animated 
model of an atom. This atom has a single sphere at the center to represent the nucleus 
and three electrons in orbit about the atom. We use an orthographic projection, as we 
have previously in this book. 


Our ATOM program uses the GLUT timer callback mechanism (discussed in Chapter 2, 
“Using OpenGL”) to redraw the scene about 10 times per second. Each time the 
RenderScene function is called, the angle of revolution about the nucleus is incremented. 
Also, each electron lies in a different plane. Listing 4.1 shows the RenderScene function 
for this example, and the output from the ATOM program is shown in Figure 4.16. 
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LISTING 4.1 RenderScene Function from ATOM Sample Program 


// Called to draw scene 

void RenderScene(void) 

{ 
// Angle of revolution around the nucleus 
static GLfloat fElecti = 0.0f; 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


// Reset the modelview matrix 


glMatrixMode(GL_MODELVIEW) ; 
glLoadIdentity(); 


// Translate the whole scene out and into view 
// This is the initial viewing transformation 
glTranslatef(0.0f, @.0f, -100.0f); 

// Red Nucleus 


glColor3ub(255, 0, 0); 
glutSolidSphere(10.0f, 15, 15); 


// Yellow Electrons 
glColor3ub(255,255,0) ; 

// First Electron Orbit 

// Save viewing transformation 


glPushMatrix(); 


// Rotate by angle of revolution 
glRotatef(fElect1, 0.0f, 1.0f, 0.0f); 


// Translate out from origin to orbit distance 
glTranslatef(90.0f, @.O0f, @.0f); 


// Draw the electron 
glutSolidSphere(6.0f, 15, 15); 


// Restore the viewing transformation 
glPopMatrix(); 


LISTING 4.1 Continued 
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// Second Electron Orbit 
glPushMatrix(); 

glRotatef(45.0f, @.0f, O.0f, 1.0f); 
glRotatef(fElecti, 0.0f, 1.0f, 0.0f); 
glTranslatef(-70.0f, 0.0f, @.Of); 
glutSolidSphere(6.@f, 15, 15); 
glPopMatrix(); 


// Third Electron Orbit 

glPushMatrix(); 

glRotatef(360.0f, -45.0f, 0.0f, 0.0f, 1.0f); 
glRotatef(fElect1, 0.0f, 1.0f, 0.0f); 
glTranslatef(0.0f, 0.0f, 60.0f); 
glutSolidSphere(6.0f, 15, 15); 
glPopMatrix(); 


// Increment the angle of revolution 
fElect1 += 10.0f; 
if(fElect1 > 360.0f) 

fElecti = 0.0f; 


// Show the image 
glutSwapBuffers(); 


FIGURE 4.16 


OpenGL Atom 


Output from the ATOM sample program. 
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Let’s examine the code for placing one of the electrons, a couple of lines at a time. The 
first line saves the current modelview matrix by pushing the current transformation on 
the stack: 


// First Electron Orbit 
// Save viewing transformation 
glPushMatrix(); 


Now the coordinate system appears to be rotated around the y-axis by an angle, fElect1: 


// Rotate by angle of revolution 
glRotatef(fElect1, 0.0f, 1.0f, 0.0f); 


The electron is drawn by translating down the newly rotated coordinate system: 


// Translate out from origin to orbit distance 
glTranslatef(90.0f, 0.O0f, 0.0f); 


Then the electron is drawn (as a solid sphere), and we restore the modelview matrix by 
popping it off the matrix stack: 


// Draw the electron 
glutSolidSphere(6.0f, 15, 15); 


// Restore the viewing transformation 
glPopMatrix() ; 


The other electrons are placed similarly. 


Using Projections 


In our examples so far, we have used the modelview matrix to position our vantage point 
of the viewing volume and to place our objects therein. The projection matrix actually 
specifies the size and shape of our viewing volume. 


Thus far in this book, we have created a simple parallel viewing volume using the function 
glOrtho, setting the near and far, left and right, and top and bottom clipping coordinates. 
When the projection matrix is loaded with the identity matrix, the diagonal line of 1s 
specifies that the clipping planes extend from the origin to +1 or -1 in all directions. The 
projection matrix by itself does no scaling or perspective adjustments unless you load a 
perspective projection matrix. 


The next two sample programs, ORTHO and PERSPECT, are not covered in detail from the 
standpoint of their source code. These examples use lighting and shading that we haven’t 
covered yet to help highlight the differences between an orthographic and a perspective 
projection. These interactive samples make it much easier for you to see firsthand how the 
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projection can distort the appearance of an object. If possible, you should run these exam- 
ples while reading the next two sections. 


Orthographic Projections 

An orthographic projection, used for most of this book so far, is square on all sides. The 
logical width is equal at the front, back, top, bottom, left, and right sides. This produces a 
parallel projection, which is useful for drawings of specific objects that do not have any 
foreshortening when viewed from a distance. This is good for CAD, 2D graphics such as 
text, or architectural drawings for which you want to represent the exact dimensions and 
measurements onscreen. 


Figure 4.17 shows the output from the sample program ORTHO in this chapter’s subdirec- 
tory on the CD. To produce this hollow, tube-like box, we used an orthographic projection 
just as we did for all our previous examples. Figure 4.18 shows the same box rotated more 
to the side so you can see how long it actually is. os 


Orthographic Projection Example 
File Help 


FIGURE 4.17 A hollow square tube shown with an orthographic projection. 


Otthographic Projection Example BEE 
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FIGURE 4.18 A side view showing the length of the square tube. 
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In Figure 4.19, you’re looking directly down the barrel of the tube. Because the tube does 
not converge in the distance, this is not an entirely accurate view of how such a tube 
appears in real life. To add some perspective, we must use a perspective projection. 


FIGURE 4.19 Looking down the barrel of the tube. 


Perspective Projections 

A perspective projection performs perspective division to shorten and shrink objects that 
are farther away from the viewer. The width of the back of the viewing volume does not 
have the same measurements as the front of the viewing volume after being projected to 
the screen. Thus, an object of the same logical dimensions appears larger at the front of 

the viewing volume than if it were drawn at the back of the viewing volume. 


The picture in our next example is of a geometric shape called a frustum. A frustum is a 
truncated section of a pyramid viewed from the narrow end to the broad end. Figure 4.20 
shows the frustum, with the observer in place. 


Perspective viewing volume 


Observer 


ra | 


near 
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FIGURE 4.20 A perspective projection defined by a frustum. 


Using Projections 


You can define a frustum with the function glFrustum. Its parameters are the coordinates 
and distances between the front and back clipping planes. However, glFrustum is not intu- 
itive about setting up your projection to get the desired effects. The utility function 
gluPerspective is easier to use and somewhat more intuitive for most purposes: 


void gluPerspective(GLdouble fovy, GLdouble aspect, 
GLdouble zNear, GLdouble zFar); 


Parameters for the gluPerspective function are a field-of-view angle in the vertical direc- 
tion, the aspect ratio of the height to width, and the distances to the near and far clipping 
planes (see Figure 4.21). You find the aspect ratio by dividing the width (w) by the height 
(h) of the window or viewport. 


Observer 


FIGURE 4.21 The frustum as defined by gluPerspective. 


Listing 4.2 shows how we change our orthographic projection from the previous examples 
to use a perspective projection. Foreshortening adds realism to our earlier orthographic 
projections of the square tube (see Figures 4.22, 4.23, and 4.24). The only substantial 
change we made for our typical projection code in Listing 4.2 was substituting the call to 
gluOrtho2D with gluPerspective. 


Perspective Piojection Example 


FIGURE 4.22 The square tube with a perspective projection. 
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Perspective Projection Example 


FIGURE 4.23 Side view with foreshortening. 


Perspective Projection Example (Joh) 
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FIGURE 4.24 Looking down the barrel of the tube with perspective added. 


LISTING 4.2 Setting Up the Perspective Projection for the PERSPECT Sample Program 


// Change viewing volume and viewport. Called when window is resized 
void ChangeSize(GLsizei w, GLsizei h) 


{ 
GLfloat fAspect; 


// Prevent a divide by zero 
if(h == @) 
h= 1; 


// Set viewport to window dimensions 
glViewport(@, @, w, h); 
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LISTING 4.2 Continued 
fAspect = (GLfloat)w/(GLfloat)h; 


// Reset coordinate system 
glMatrixMode(GL_PROJECTION) ; 
glLoadidentity(); 


// Produce the perspective projection 
gluPerspective(60.0f, fAspect, 1.0, 400.0); 


glMatrixMode(GL_MODELVIEW) ; 
glLoadidentity(); 
} 


We made the same changes to the ATOM example in ATOM2 to add perspective. Run the 
two side by side, and you see how the electrons appear to be smaller as they swing far 
away behind the nucleus. 


A Far-Out Example 


For a more complete example showing modelview manipulation and perspective projec- 

tions, we have modeled the Sun and the Earth/Moon system in revolution in the SOLAR 
example program. This is a classic example of nested transformations with objects being 

transformed relative to one another using the matrix stack. We have enabled some light- 
ing and shading for drama so you can more easily see the effects of our operations. You’ll 
learn about shading and lighting in the next two chapters. 


In our model, the Earth moves around the Sun, and the Moon revolves around the Earth. 
A light source is placed at the center of the Sun, which is drawn without lighting to make 
it appear to be the glowing light source. This powerful example shows how easily you can 
produce sophisticated effects with OpenGL. 


Listing 4.3 shows the code that sets up the projection and the rendering code that keeps 
the system in motion. A timer elsewhere in the program triggers a window redraw 10 
times a second to keep the RenderScene function in action. Notice in Figures 4.25 and 
4.26 that when the Earth appears larger, it’s on the near side of the Sun; on the far side, it 
appears smaller. 


LISTING 4.3 Code That Produces the Sun/Earth/Moon System 


// Change viewing volume and viewport. Called when window is resized 
void ChangeSize(GLsizei w, GLsizei h) 

{ 

GLfloat fAspect; 
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LISTING 4.3 Continued 


// Prevent a divide by zero 
if(h == ) 
he=_ 13 


// Set viewport to window dimensions 
glViewport(®, @, w, h); 


// Calculate aspect ratio of the window 
fAspect = (GLfloat)w/(GLfloat)h; 


// Set the perspective coordinate system 
glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 


// Field of view of 45 degrees, near and far planes 1.0 and 425 
gluPerspective(45.0f, fAspect, 1.0, 425.0); 


// Modelview matrix reset 
glMatrixMode(GL_MODELVIEW) ; 
glLoadidentity(); 

} 


// Called to draw scene 
void RenderScene(void) 
{ 
// Earth and Moon angle of revolution 
static float fMoonRot = 0.0f; 
static float fEarthRot = 0.0f; 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


// Save the matrix state and do the rotations 
glMatrixMode (GL_MODELVIEW) ; 
glPushMatrix(); 


// Translate the whole scene out and into view 
glTranslatef(0.0f, 0.0f, -300.0f); 


// Set material color, to yellow 
// Sun 
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glColor3ub(255, 255, Q); 
glDisable(GL_LIGHTING) ; 
glutSolidSphere(15.0f, 15, 15); 
glEnable(GL_LIGHTING) ; 


// Position the light after we draw the sun! 
glLightfv(GL_LIGHT®,GL_POSITION, lightPos) ; 


// Rotate coordinate system 
glRotatef(fEarthRot, 0.0f, 1.0f, 0.0f); 


// Draw the Earth 

glColor3ub(0,0,255) ; 

glTranslatef(105.0f ,0.0f,0.0f); se 
glutSolidSphere(15.0f, 15, 15); 


// Rotate from Earth-based coordinates and draw Moon 
glColor3ub (200,200,200) ; 
glRotatef(fMoonRot,@.0f, 1.0f, 0.0f); 
glTranslatef(30.0f, 0.0f, 0.0f); 
fMoonRot+= 15.0f; 
if (fMoonRot > 360.0f) 

fMoonRot = @.0f; 


glutSolidSphere(6.0f, 15, 15); 


// Restore the matrix state 
glPopMatrix(); // Modelview matrix 


// Step earth orbit 5 degrees 

fEarthRot += 5.0f; 

if(fEarthRot > 360.0f) 
fEarthRot = 0.0f; 


// Show the image glutSwapBuffers(); 
} 
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Earth/Moon/Sun System 


FIGURE 4.25 


Eatth/Moon/Sun System 


FIGURE 4.26 The Sun/Earth/Moon system with the Earth on the far side. 


Advanced Matrix Manipulation 


These higher-level “canned” transformations (for rotation, scaling, and translation) are 
great for many simple transformation problems. Real power and flexibility, however, are 
afforded to those who take the time to understand using matrices directly. Doing so is not 
as hard as it sounds, but first you need to understand the magic behind those 16 numbers 
that make up a 4x4 transformation matrix. 


OpenGL represents a 4x4 matrix not as a two-dimensional array of floating-point values, 
but as a single array of 16 floating-point values. This approach is different from many 
math libraries, which do take the two-dimensional array approach. For example, OpenGL 
prefers the first of these two examples: 


GLfloat matrix[16]; // Nice OpenGL friendly matrix 
GLfloat matrix[4][4]; // Popular, but not as efficient for OpenGL 


OpenGL can use the second variation, but the first is a more efficient representation. The 
reason for this will become clear in a moment. These 16 elements represent the 4x4 
matrix, as shown in Figure 4.27. When the array elements traverse down the matrix 
columns one by one, we call this column-major matrix ordering. In memory, the 4x4 
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approach of the two-dimensional array (the second option in the preceding code) is laid 
out in a row-major order. In math terms, the two orientations are the transpose of one 
another. 


Mp G4 dg Q)2 
Q)} G5 do Q)3 
Q) M6 Gio O14 
G3 7 Q)) M5 


FIGURE 4.27 Column-major matrix ordering. 


The real magic lies in the fact that these 16 values represent a particular position in space 
and an orientation of the three axes with respect to the eye coordinate system (remember 
that fixed, unchanging coordinate system we talked about earlier). Interpreting these 
numbers is not hard at all. The four columns each represent a four-element vector. To keep 
things simple for this book, we focus our attention to just the first three elements of these 
vectors. The fourth column vector contains the x, y, and z values of the transformed coor- 
dinate system. When you call glTranslate on the identity matrix, all it does is put your 
values for x, y, and z in the 12", 13", and 14" position of the matrix. 


The first three columns are just directional vectors that represent the orientation (vectors 
here are used to represent a direction) of the x-, y-, and z-axes in space. For most purposes, 
these three vectors are always at 90° angles from each other. The mathematical term for 
this (in case you want to impress your friends) is orthonormal. Figure 4.28 shows the 4x4 
transformation matrix with the column vectors highlighted. Notice the last row of the 
matrix is all Os with the exception of the very last element, which is 1. 


<< 2x << X axis direction 
<< << V axis direction 


o 
o 
Oo 
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FIGURE 4.28 How a 4x4 matrix represents a position and orientation in 3D space. 


The most amazing thing is that if you have a 4x4 matrix that contains the position and 
orientation of a different coordinate system, and you multiply a vertex (as a column 
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matrix or vector) by this matrix, the result is a new vertex that has been transformed to 
the new coordinate system. This means that any position in space and any desired orien- 
tation can be uniquely defined by a 4x4 matrix, and if you multiply all of an object’s 
vertices by this matrix, you transform the entire object to the given location and orienta- 
tion in space! 


HARDWARE TRANSFORMATIONS 


Many OpenGL implementations have what is called hardware T&L (for Transform and Lighting). 
This means that the transformation matrix multiplies many thousands of vertices on special 
graphics hardware that performs this operation very, very fast. (Intel and AMD can eat their 
hearts out!) However, functions such as glRotate and glScale, which create transformation 
matrices for you, are usually not hardware accelerated because typically they represent an 
exceedingly small fraction of the enormous amount of matrix math that must be done to draw a 
scene. 


So why does OpenGL insist on using column-major ordering? Simple. To get an axis- 
directional vector or the translation from a matrix, the implementation simply does one 
copy from memory to get all the data found in one place. In row-major ordering, the soft- 
ware must access three different memory locations (or four) to get just a single vector from 
the matrix. 


Loading a Matrix 

After you have a handle on the way the 4x4 matrix represents a given location and orien- 
tation, you may to want to compose and load your own transformation matrices. You can 
load an arbitrary column-major matrix into the projection, modelview, or texture matrix 
stacks by using the following function: 


glLoadMatrixf(GLfloat m); 


or 


glLoadMatrixd(GLfloat m); 


Most OpenGL implementations store and manipulate pipeline data as floats and not 
doubles; consequently, using the second variation may incur some performance penalty 
because 16 double-precision numbers must be converted into single-precision floats. 


The following code shows an array being loaded with the identity matrix and then being 
loaded into the modelview matrix stack. This example is equivalent to calling 
glLoadIdentity using the higher-level functions: 


// Load an identity matrix 
glFloat m[] = { 1.0f, 0.0f, 0.0f, 0.Of, // X Column 
@.0f, 1.0f, 0.0f, 0.Of, // Y Column 


Q.0f, 0.0f, 1.0f, 0.0f, // Z Column 
Q.O0f, O.O0f, O@.0f, 1.0Ff }; // Translation 


glMatrixMode(GL_MODELVIEW) ; 
glLoadMatrixf(m) ; 


Although internally OpenGL implementations prefer column-major ordering (and for 
good reason!), OpenGL does provide functions to load a matrix in row-major ordering. 
The following two functions perform the transpose operation on the matrix when loading 
it on the matrix stack: 


void glLoadTransposeMatrixf(GLfloat m); 


and 


void glLoadTransposeMatrixd(GLdouble m); 


Performing Your Own Transformations 

Let’s look at an example now that shows how to create and load your own transformation 
matrix—the hard way! In the sample program TRANSFORM, we draw a torus (a doughnut- 
shaped object) in front of our viewing location and make it rotate in place. The function 
DrawTorus does the necessary math to generate the torus’s geometry and takes as an argu- 
ment a 4x4 transformation matrix to be applied to the vertices. We create the matrix and 
apply the transformation manually to each vertex to transform the torus. Let’s start with 
the main rendering function in Listing 4.4. 


LISTING 4.4 Code to Set Up the Transformation Matrix While Drawing 


void RenderScene(void) 


if 

GLTMatrix  transformationMatrix; // Storage for rotation matrix 
static GLfloat yRot = 0.0f; // Rotation angle for animation 
yRot += 0.5f; 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


// Build a rotation matrix 
gltRotationMatrix(gltDegToRad(yRot), @.0f, 1.0f, 0.Of, 
transformationMatrix) ; 


transformationMatrix[12] = 0.0f; 
transformationMatrix[13] = 0.0f; 
transformationMatrix[14] = -2.5f; 
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LISTING 4.4 Continued 


DrawTorus(transformationMatrix) ; 


// Do the buffer Swap 
glutSwapBuffers() ; 
} 


We begin by declaring storage for the matrix here: 

GLTMatrix transformationMatrix; // Storage for rotation matrix 

The data type GLTMatrix is of our own design and is simply a typedef declared in 
gltools.h for a floating-point array 16 elements long: 

typedef GLfloat GLTMatrix[16]; // A column major 4x4 matrix of type GLfloat 
The animation in this sample works by continually incrementing the variable yRot that 


represents the rotation around the y-axis. After clearing the color and depth buffer, we 
compose our transformation matrix as follows: 


gltRotationMatrix(gltDegToRad(yRot), @.0f, 1.0f, 0.0f, transformationMatrix) ; 


transformationMatrix[12] = 0.0f; 
transformationMatrix[13] = 0.0f; 
transformationMatrix[14] = -2.5f; 


Here, the first line contains a call to another g1Tools function, gl1tRotationMatrix. This 
function takes a rotation angle in radians (for more efficient calculations) and three argu- 
ments specifying a vector around which you want the rotation to occur. With the excep- 
tion of the angle being in radians instead of degrees, this is almost exactly like the 
OpenGL function glRotate. The last argument is a matrix into which you want to store 
the resulting rotation matrix. The macro function g1tDegToRad does an in-place conver- 
sion from degrees to radians. 


As you saw in Figure 4.28, the last column of the matrix represents the translation of the 
transformation. Rather than do a full matrix multiplication, we can simply inject the 
desired translation directly into the matrix. Now the resulting matrix represents both a 
translation in space (a location to place the torus) and then a rotation of the object’s coor- 
dinate system applied at that location. 


Next, we pass this transformation matrix to the DrawTorus function. You do not need to 
list the entire function to create a torus here, but focus your attention to these lines: 


objectVertex[0] 
objectVertex[1] = yO*r; 
objectVertex[2] = z; 
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gltTransformPoint(objectVertex, mTransform, transformedVertex) ; 
glVertex3fv(transformedVertex) ; 


The three components of the vertex are loaded into an array and passed to the function 
gltTransformPoint. This g1Tools function performs the multiplication of the vertex 
against the matrix and returns the transformed vertex in the array transformedVertex. We 
then use the vector version of glVertex and send the vertex data down to OpenGL. The 
result is a spinning torus, as shown in Figure 4.29. 


FIGURE 4.29 The spinning torus, doing our own transformations. 


It is important that you see at least once the real mechanics of how vertices are trans- 
formed by a matrix using such a drawn-out example. As you progress as an OpenGL 
programmer, you will find that the need to transform points manually will arise for tasks 
that are not specifically related to rendering operations, such as collision detection 
(bumping into objects), frustum culling (throwing away and not drawing things you can’t 
see), and some other special effects algorithms. 


For geometry processing, however, the TRANSFORM sample program is very inefficient. 
We are letting the CPU do all the matrix math instead of letting OpenGL’s dedicated hard- 
ware do the work for us (which is much faster than the CPU!). In addition, because 
OpenGL has the modelview matrix, all our transformed points are being multiplied yet 
again by the identity matrix. This does not change the value of our transformed vertices, 
but it is still a wasted operation. 
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For the sake of completeness, we provide an improved example, TRANSFORMGL, that 
instead uses our transformation matrix but hands it over to OpenGL using the function 
glLoadMatrixf. We eliminate our DrawTorus function with its dedicated transformation 
code and use a more general-purpose torus drawing function, gltDrawTorus, from the 
glTools library. The relevant code is shown in Listing 4.5. 


LISTING 4.5 Loading the Transformation Matrix Directly into OpenGL 


// Build a rotation matrix 
gltRotationMatrix(gltDegToRad(yRot), @.0f, 1.0f, 0.Of, 
transformationMatrix) ; 


transformationMatrix[12] = 0.0f; 
transformationMatrix[13] = 0.0f; 
transformationMatrix[14] = -2.5f; 


glLoadMatrixf (transformationMatrix) ; 


gltDrawTorus(@.35, 0.15, 40, 20); 


Adding Transformations Together 


In the preceding example, we simply constructed a single transformation matrix and 
loaded it into the modelview matrix. This technique had the effect of transforming any 
and all geometry that followed by that matrix before being rendered. As you’ve seen in 
the other previous examples, we often add one transformation to another. For example, 
we used glTranslate followed by glRotate to first translate and then rotate an object 
before being drawn. Behind the scenes, when you call multiple transformation functions, 
OpenGL performs a matrix multiplication between the existing transformation matrix and 
the one you are adding or appending to it. For example, in the TRANSFORMGL example, 
we might replace the code in Listing 4.5 with something like the following: 


glPushMatrix(); 
glTranslatef(0.0f, 0.0f, -2.5f); 
glRotatef(yRot, 0.0f, 1.0f, @.Of); 


gltDrawTorus(@.35, 0.15, 40, 20); 
glPopMatrix(); 


Using this approach has the effect of saving the current identity matrix, multiplying the 
translation matrix, multiplying the rotation matrix, and then drawing the torus by the 
result. You can do these multiplications yourself by using the glTools function 
gltMultiplyMatrix, as shown here: 


Moving Around in OpenGL Using Cameras and Actors 


GLTMatrix rotationMatrix, translationMatrix, transformationMatrix; 


gltRotationMatrix(gltDegToRad(yRot), @.0f, 1.0f, @.0f, rotationMatrix) ; 
gltTranslationMatrix(®.0f, 0.0f, -2.5f, translationMatrix) ; 
gltMultiplyMatrix(translationMatrix, rotationMatrix, transformationMatrix) ; 
glLoadMatrixf (transformationMatrix) ; 


gltDrawTorus(0.35f, 0.15f, 40, 20); 


OpenGL also has its own matrix multiplication function, g1MultMatrix, that takes a 
matrix and multiplies it by the currently loaded matrix and stores the result at the top of 
the matrix stack. In our final code fragment, we once again show code equivalent to the 
preceding, but this time we let OpenGL do the actual multiplication: 


GLTMatrix rotationMatrix, translationMatrix, transformationMatrix; 


glPushMatrix(); 
gltRotationMatrix(gltDegToRad(yRot), @.0f, 1.0f, @.@f, rotationMatrix) ; 
gltTranslationMatrix(0.0f, 0.0f, -2.5f, translationMatrix) ; 


glMultMatrixf (translationMatrix) ; 
glMultMatirxf (rotationMatrix) ; 


gltDrawTorus(0.35f, 0.15f, 40, 20); 
glPopMatrix(); 


Once again, you should remember that the glMultMatrix functions and other high-level 
functions that do matrix multiplication (glRotate, gl1Scale, glTranslate) are not being 
performed by the OpenGL hardware, but usually by your CPU. 


Moving Around in OpenGL Using Cameras and Actors 


To represent a location and orientation of any object in your 3D scene, you can use a 
single 4x4 matrix that represents its transform. Working with matrices directly, however, 
can still be somewhat awkward, so programmers have always sought ways to represent a 
position and orientation in space more succinctly. Fixed objects such as terrain are often 
untransformed, and their vertices usually specify exactly where the geometry should be 
drawn in space. Objects that move about in the scene are often called actors, paralleling 
the idea of actors on a stage. 


Actors have their own transformations, and often other actors are transformed not only 

with respect to the world coordinate system (eye coordinates), but with respect to other 

actors. Each actor with its own transformation is said to have its own frame of reference, 
or local object coordinate system. It is often useful to translate between local and world 

coordinate systems and back again for many nonrendering-related geometric tests. 
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An Actor Frame 


A simple and flexible way to represent a frame of reference is to use a data structure (or 
class in C++) that contains a position in space, a vector that points forward, and a vector 
that points upward. Using these quantities, you can uniquely identify a given position and 
orientation in space. The following example from the glTools library is a GLFrame data 
structure that can store this information all in one place: 


typedef struct{ 
GLTVector3f vLocation; 
GLTVector3f vUp; 
GLTVector3f vForward; 
} GLTFrame; 


Using a frame of reference such as this to represent an object’s position and orientation is 
a very powerful mechanism. To begin with, you can use this data directly to create a 4x4 
transformation matrix. Referring to Figure 4.28, the up vector becomes the y column of 
the matrix, whereas the forward-looking vector becomes the z column vector and the posi- 
tion is the translation column vector. This leaves only the x column vector, and because 
we know all three axes are perpendicular to one another (orthonormal), we can calculate 
the x column vector by performing the cross product of the y and z vectors. Listing 4.6 
shows the g1Tools function g1tGetMatrixFromFrame, which does exactly that. 


LISTING 4.6 Code to Derive a 4x4 Matrix from a Frame 


FUTTTITTITTT TTT TTT TTT TTL 
// Derives a 4x4 transformation matrix from a frame of reference 
void gltGetMatrixFromFrame(GLTFrame *pFrame, GLTMatrix mMatrix) 

{ 

GLTVector3f vXAxis; // Derived X Axis 


// Calculate X Axis 
gltVectorCrossProduct(pFrame->vUp, pFrame->vForward, vXAxis); 


// Just populate the matrix 

// X column vector 

memcpy(mMatrix, vXAxis, sizeof(GLTVector) ); 
mMatrix[3] = 0.0f; 


// y column vector 
memcpy(mMatrixt+4, pFrame->vUp, sizeof(GLTVector) ) ; 
mMatrix[7] = 0.0f; 


Moving Around in OpenGL Using Cameras and Actors 


LISTING 4.6 Continued 


// z column vector 
memcpy(mMatrix+8, pFrame->vForward, sizeof (GLTVector) ); 
mMatrix[11] = 0.0f; 


// Translation/Location vector 

memcpy(mMatrixt12, pFrame->vLocation, sizeof (GLTVector) ) ; 
mMatrix[15] = 1.0f; 

} 


Applying an actor’s transform is as simple as calling glMultMatrixf with the resulting 
matrix. 


Euler Angles: “Use the Frame, Luke!” 


Many graphics programming books recommend an even simpler mechanism for storing 

an object’s position and orientation: Euler angles. Euler angles require less space because 

you essentially store an object’s position and then just three angles—representing a rota- 
tion around the x-, y-, and z-axes—sometimes called yaw, pitch, and roll. A structure such 
as this might represent an airplane’s location and orientation: 


struct EULER { 
GLTVector3f vPosition; 


GLfloat fRoll; 
GLfloat fPitch; 
GLfloat fYaw; 
}; 


Euler angles are a bit slippery and are sometimes called “oily angles” by some in the indus- 
try. The first problem is that a given position and orientation can be represented by more 
than one set of Euler angles. Having multiple sets of angles can lead to problems as you 
try to figure out how to smoothly move from one orientation to another. Occasionally, a 
second problem called “gimbal lock” comes up; this problem makes it impossible to 
achieve a rotation around one of the axes. Lastly, Euler angles make it more tedious to 
calculate new coordinates for simply moving forward along your line of sight or trying to 
figure out new Euler angles if you want to rotate around one of your own local axes. 


Some literature today tries to solve the problems of Euler angles by using a mathematical 
tool called quaternions. Quaternions, which can be difficult to understand, really don’t 
solve any problems with Euler angles that you can’t solve on your own by just using the 
frame of reference method covered previously. We already promised that this book would 
not get too heavy on the math, so we will not debate the merits of each system here. But 
we should say that the quaternion versus linear algebra (matrix) debate is more than 100 
years old and by far predates their application to computer graphics! 
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Camera Management 

There is really no such thing as a camera transformation in OpenGL. We use the camera as 
a useful metaphor to help us manage our point of view in some sort of immersive 3D 
environment. If we envision a camera as an object that has some position in space and 
some given orientation, we find that our current frame of reference system can represent 
both actors and our camera in a 3D environment. 


To apply a camera transformation, we take the camera’s actor transform and flip it so that 

moving the camera backward is equivalent to moving the whole world forward. Similarly, 

turning to the left is equivalent to rotating the whole world to the right. To render a given 
scene, we usually take the approach outlined in Figure 4.30. 


The OpenGL utility library contains a function that uses the same data we stored in our 
frame structure to create our camera transformation: 


void gluLookAt(GLdouble eyex, GLdouble eyey, GLdouble eyez, 
GLdouble centerx, GLdouble centery, GLdouble centerz, 
GLdouble upx, GLdouble upy, GLdouble upz); 


Save Identity Matrix 


Apply camera transform 
Draw stuff that doesn’t move 
Draw moving stuff (Actors) 
i Save camera transform 
| Apply actor transform 
>) Draw actor geometry 
Restore camera transform 


Restore identity matrix 


FIGURE 4.30 Typical rendering loop for a 3D environment. 


This function takes the position of the eye point, a point directly in front of the eye point, 
and the direction of the up vector. The g1Tools library also contains a shortcut function 
that performs the equivalent action using a frame of reference: 


void gltApplyCameraTransform(GLTFrame *pCamera) ; 


Bringing It All Together 


Now let’s work through one final example for this chapter to bring together all the 
concepts we have discussed so far. In the sample program SPHEREWORLD, we create a 
world populated by a number of spheres (Sphere World) placed at random locations on 
the ground. Each sphere is represented by an individual GLTFrame structure for its location 
and orientation. We also use the frame to represent a camera that can be moved about 
Sphere World using the keyboard arrow keys. In the middle of Sphere World, we use the 
simpler high-level transformation routines to draw a spinning torus with another sphere 
in orbit around it. 


Bringing It All Together 


This example combines all the ideas we have discussed thus far and shows them working 
together. In addition to the main source file sphereworld.c, the project also includes the 
torus.c, matrixmath.c, and framemath.c modules from the glTools library found in the 
\common subdirectory. We do not provide the entire listing here because it uses the same 
GLUT framework as all the other samples, but the important functions are shown in 
Listing 4.7. 


LISTING 4.7 Main Functions for the SPHEREWORLD Sample 


#define NUM_SPHERES 50 
GLTFrame spheres[NUM_SPHERES] ; 
GLTFrame frameCamera; 


FTTTLTLTT TTT TTT TTT TT TTT 
// This function does any needed initialization on the rendering 
// context. 
void SetupRC() 

{ 


int iSphere; 


// Bluish background 
glClearColor(0.0f, @.0f, .50f, 1.0f ); 


// Draw everything as wire frame 
glPolygonMode(GL_FRONT_AND_ BACK, GL_LINE); 


gltInitFrame(&frameCamera); // Initialize the camera 


// Randomly place the sphere inhabitants 
for(iSphere = @; iSphere < NUM_SPHERES; iSphere++) 
{ 
gltInitFrame(&spheres[iSphere] ) ; // Initialize the frame 


// Pick a random location between -20 and 20 at .1 increments 
spheres[iSphere].vLocation[®] = (float)((rand() % 400) - 200) * 0.1f; 
spheres[iSphere].vLocation[1] = 0.0f; 

spheres[iSphere].vLocation[2] (float) ((rand() % 400) - 200) * 0.1f; 
} 


TLTTTTTT TTT TTT TATA TAT TAT TT ATT 
// Draw a gridded ground 
void DrawGround(void) 


{ 
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LISTING 4.7 Continued 


GLfloat fExtent = 20.0f; 
GLfloat fStep = 1.0f; 
GLfloat y = -0.4f; 

GLint iLine; 


glBegin(GL_LINES) ; 
for(iLine = -fExtent; iLine <= fExtent; iLine += fStep) 
{ 
glVertex3f(iLine, y, fExtent); // Draw Z lines 
glVertex3f(iLine, y, -fExtent); 


glVertex3f(fExtent, y, iLine); 
glVertex3f(-fExtent, y, iLine); 


} 


glEnd(); 
} 


// Called to draw scene 
void RenderScene(void) 
{ 
Tnt.L 
static GLfloat yRot = 0.0f; // Rotation angle for animation 
yRot += 0.5f; 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


glPushMatrix() ; 
gltApplyCameraTransform(&frameCamera) ; 


// Draw the ground 
DrawGround() ; 


// Draw the randomly located spheres 
for(i = 0; i < NUM_SPHERES; i++) 
{ 
glPushMatrix(); 
gltApplyActorTransform(&spheres[i]) ; 
glutSolidSphere(@.1f, 13, 26); 


LISTING 4.7 Continued 


Bringing It All Together 


glPopMatrix(); 
} 


glPushMatrix(); 
glTranslatef(Q.0f, @.0f, -2.5f); 


glPushMatrix(); 
glRotatef(-yRot * 2.0f, 0.0f, 1 
glTranslatef(1.0f, 0.0f, 0.0f); 
glutSolidSphere(@.1f, 13, 26); 
glPopMatrix() ; 


glRotatef(yRot, 0.0f, 1.0f, 0.0f); 
gltDrawTorus(@.35, 0.15, 40, 20); 
glPopMatrix(); 
glPopMatrix(); 


// Do the buffer Swap 
glutSwapBuffers() ; 
} 


-OF, 0.0f); 


// Respond to arrow keys by moving the camera frame of reference 


void SpecialKeys(int key, int x, int y) 
{ 
if(key == GLUT_KEY_UP) 


gltMoveFrameForward(&frameCamera, .1f); 


if(key == GLUT_KEY_DOWN) 
gltMoveFrameForward (&frameCamera, 


if(key == GLUT_KEY_LEFT) 


-0.1Ff); 


gltRotateFrameLocalY(&frameCamera, @.1); 


if(key == GLUT_KEY_RIGHT) 


gltRotateFrameLocaly(&frameCamera, -Q.1); 


// Refresh the Window 
glutPostRedisplay(); 
} 
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The first few lines contain a macro to define the number of spherical inhabitants as 50. 
Then we declare an array of frames and another frame to represent the camera: 


#define NUM_SPHERES 50 
GLTFrame spheres[NUM_SPHERES] ; 
GLTFrame frameCamera; 


The SetupRC function calls the g1Tools function gltInitFrame on the camera to initialize 
it as being at the origin and pointing down the negative z-axis (the OpenGL default 
viewing orientation): 


gltInitFrame(&frameCamera); // Initialize the camera 


You can use this function to initialize any frame structure, or you can initialize the struc- 
ture yourself to have any desired position and orientation. Next, a loop initializes the 
array of sphere frames and selects a random x and z location for their positions: 


// Randomly place the sphere inhabitants 
for(iSphere = @; iSphere < NUM_SPHERES; iSphere++) 
{ 
gltInitFrame(&spheres[iSphere]) ; // Initialize the frame 


// Pick a random location between -20 and 20 at .1 increments 
spheres[iSphere].vLocation[®@] = (float)((rand() % 400) - 200) * 0.1f; 
spheres[iSphere].vLocation[1] = 0.0f; 

spheres[iSphere] .vLocation[2] (float) ((rand() % 400) - 200) * 0.1f; 
} 


The DrawGround function then draws the ground as a series of criss-cross grids using a 
series of GL_LINE segments: 


FULTTTTTATT TTT TTT TTT TT 
// Draw a gridded ground 
void DrawGround(void) 

{ 

GLfloat fExtent = 20.0f; 

GLfloat fStep = 1.0f; 

GLfloat y = -0.4f; 

GLint iLine; 


glBegin(GL_LINES) ; 
for(iLine = -fExtent; iLine <= fExtent; iLine += fStep) 
{ 
glVertex3f(iLine, y, fExtent); // Draw Z lines 
glVertex3f(iLine, y, -fExtent); 


Bringing It All Together 


glVertex3f(fExtent, y, iLine); 
glVertex3f(-fExtent, y, iLine); 
} 


glEnd(); 
} 


The RenderScene function draws the world from our point of view. Note that we first save 
the identity matrix and then apply the camera transformation using the glTools helper 
function gltApplyCameraTransform. The ground is static and is transformed by the camera 
only to appear that you are moving over it: 


glPushMatrix(); 
gltApplyCameraTransform(&frameCamera) ; 


// Draw the ground 
DrawGround() ; 


Then we draw each of the randomly located spheres. The gltApplyActorTransform func- 
tion creates a transformation matrix from the frame of reference and multiplies it by the 
current matrix (which is the camera matrix). Each sphere must have its own transform 
relative to the camera, so the camera is saved each time with a call to glPushMatrix and 
restored again with glPopMatrix to get ready for the next sphere or transformation: 


// Draw the randomly located spheres 
for(i = @; i < NUM_SPHERES; i++) 
{ 
glPushMatrix(); 
gltApplyActorTransform(&spheres[i]) ; 
glutSolidSphere(Q.1f, 13, 26); 
glPopMatrix(); 
} 


Now for some fancy footwork! First, we move the coordinate system a little further down 
the z-axis so that we can see what we are going to draw next. We save this location and 
then perform a rotation, followed by a translation and the drawing of a sphere. This effect 
makes the sphere appear to revolve around the origin in front of us. We then restore our 
transformation matrix, but only so that the location of the origin is z = -2.5. Then another 
rotation is performed before the torus is drawn. This has the effect of making a torus that 
spins in place: 


glPushMatrix(); 
glTranslatef(0.0f, 0.0f, -2.5f); 
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glPushMatrix(); 
glRotatef(-yRot * 2.0f, 0.0f, 1.0f, 0.0f); 
glTranslatef(1.0f, 0.0f, 0.0f); 
glutSolidSphere(®.1f, 13, 26); 
glPopMatrix() ; 


glRotatef(yRot, 0.0f, 1.0f, 0.0f); 
gltDrawTorus(@.35, 0.15, 40, 20); 
glPopMatrix(); 
glPopMatrix(); 


The total effect is that we see a grid on the ground with many spheres scattered about at 
random locations. Out in front, we see a spinning torus, with a sphere moving rapidly in 
orbit around it. Figure 4.31 shows the result. 


FIGURE 4.31 The output from the SPHEREWORLD program. 


Finally, the SpecialKeys function is called whenever one of the arrow keys is pressed. The 
up- and down-arrow keys call the g1Tools function g1tMoveFrameForward, which simply 
moves the frame forward along its line of sight. The gltRotateFrameLocaly function 
rotates a frame of reference around its local y-axis (regardless of orientation) in response to 
the left- and right-arrow keys: 


Summary 


void SpecialKeys(int key, int x, int y) 
{ 
if (key == GLUT_KEY_UP) 
gltMoveFrameForward(&frameCamera, 0.1f); 


if (key == GLUT_KEY_DOWN) 
gltMoveFrameForward(&frameCamera, -0.1f); 


if (key == GLUT_KEY_LEFT) 
gltRotateFrameLocaly(&frameCamera, 0.1); 


if(key == GLUT_KEY_RIGHT) 
gltRotateFrameLocaly(&frameCamera, -0.1); 


// Refresh the Window 
glutPostRedisplay(); 


} 


A NOTE ON KEYBOARD POLLING 


Moving the camera in response to keystroke messages can sometimes result in less than the 
smoothest possible animation. The reason is that the keyboard repeat rate is usually no more 
than about 20 times per second. For best results, you should render at least 30 frames per 
second (with 60 being more optimal) and poll the keyboard once for each frame of animation. 
Doing this with a portability library like GLUT is somewhat tricky, but in the OS-specific chapters 
later in this book, we will cover ways to achieve the smoothest possible animation and methods 
to best create time-based animation instead of the frame-based animation (moving by a fixed 
amount each time the scene is redrawn) done here. 


Summary 


In this chapter, you learned concepts crucial to using OpenGL for creation of 3D scenes. 
Even if you can’t juggle matrices in your head, you now know what matrices are and how 
they are used to perform the various transformations. You also learned how to manipulate 
the modelview and projection matrix stacks to place your objects in the scene and to 
determine how they are viewed onscreen. 


We also showed you the functions needed to perform your own matrix magic, if you are 
so inclined. These functions allow you to create your own matrices and load them on to 
the matrix stack or multiply them by the current matrix first. The chapter also introduced 
the powerful concept of a frame of reference, and you saw how easy it is to manipulate 
frames and convert them into transformations. 


Finally, we began to make more use of the glTools library that accompanies this book. 
This library is written entirely in portable ANSI C and provides you with a handy toolkit 
of miscellaneous math and helper routines that can be used along with OpenGL. 
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Reference 


glFrustum 


Purpose: Multiplies the current matrix by a perspective matrix. 
Include File: <gl.h> 
Syntax: 


void glFrustum(GLdouble left, GLdouble right, GLdouble bottom, GLdouble top, 
GLdouble zNear, GLdouble zFar); 


Description: This function creates a perspective matrix that produces a perspective 
projection. The eye is assumed to be located at (0,0,0), with zFar being 
the distance of the far clipping plane and zNear specifying the distance 
to the near clipping plane. Both values must be positive. This function 
can adversely affect the precision of the depth buffer if the ratio of far to 
near (far/near) is large. 


Parameters: 
left, right GLdouble: Coordinates for the left and right clipping planes. 


bottom, top GLdouble: Coordinates for the bottom and top clipping planes. 

zNear, zFar GLdouble: Distance to the near and far clipping planes. Both of these 
values must be positive. 

Returns: None. 

See Also: glOrtho, glMatrixMode, glMultMatrix, glViewport 

glLoadidentity 

Purpose: Sets the current matrix to identity. 


Include File: <gl.h> 
Syntax: 
void glLoadIdentity (void) ; 


Description: This function replaces the current transformation matrix with the iden- 
tity matrix. This essentially resets the coordinate system to eye coordi- 
nates. 

Returns: None. 


See Also: glLoadMatrix, glMatrixMode, glMultMatrix, glPushMatrix 


Reference 


glLoadMatrix 
Purpose: Sets the current matrix to the one specified. 
Include File: <gl.h> 


Variations: 


void glLoadMatrixd(const GLdouble *m); 
void glLoadMatrixf (const GLfloat *m); 


Description: This function replaces the current transformation matrix with an arbi- 
trary matrix supplied. Using some of the other matrix manipulation func- 
tions, such as glLoadIdentity, glRotate, glTranslate, and glScale, 
might be more efficient. 


Parameters: 

*m GLdouble or GLfloat: This array represents a 4x4 matrix that will be used 
for the current transformation matrix. The array is stored in column- 
major order as 16 consecutive values. 

Returns: None. 

See Also: glLoadidentity, glMatrixMode, glMultMatrix, glPushMatrix 


glLoadTransposeMatrix 


Purpose: Allows a transposed 4x4 matrix to be loaded onto the matrix stack. 
Include File: <gl.h> 
Variations: 


void LoadTransposeMatrixf(GLfloat *m); 
void LoadTransposeMatrixd(GLdouble *m); 


Description: OpenGL uses 4x4 matrices in a single one-dimensional column-major 
array. A row-major ordered array, which is the transpose of the column- 
major array, may be loaded onto the stack using this function. This func- 
tion takes the matrix, transposes it, and then loads a properly formatted 
array to the top of the current matrix stack. Some OpenGL libraries may 
not export this function, even if the implementation supports it. In this 
case, a pointer to this function may be obtained via the OpenGL exten- 
sion mechanism. 


Parameters: 
*m GLfloat or GLdouble: 4x4 transposed matrix to be loaded. 
Returns: None. 


See Also: glLoadMatrix, glMultTransposeMatrix 
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glMatrixMode 

Purpose: Specifies the current matrix (GL_PROJECTION, GL_MODELVIEW, or 
GL_TEXTURE). 

Include File: <gl.h> 

Syntax: 


void glMatrixMode(GLenum mode ); 


Description: This function determines which matrix stack (GL_MODELVIEW, GL_ 
PROJECTION, or GL_TEXTURE) is used for matrix operations. 


Parameters: 
mode GLenum: Identifies which matrix stack is used for subsequent matrix oper- 
ations. Any of the values in Table 4.2 are accepted. 


TABLE 4.2 Valid Matrix Mode Identifiers for g1MatrixMode 


Mode Matrix Stack 
GL_MODELVIEW Matrix operations affect the modelview matrix stack. (Used to move objects 
around the scene.) 
GL_PROJECTION Matrix operations affect the projection matrix stack. (Used to define clipping 
volume.) 
GL_TEXTURE Matrix operations affect the texture matrix stack. (Manipulates texture coordi- 
nates.) 
Returns: None. 
See Also: glLoadMatrix, glPushMatrix 
glMultMatrix 
Purpose: Multiplies the current matrix by the one specified. 
Include File: <gl.h> 
Variations: 


void glMultMatrixd(const GLdouble *m); 
void glMultMatrixf(const GLfloat *m); 


Description: This function multiplies the currently selected matrix stack with the one 
specified. The resulting matrix is then stored as the current matrix at the 
top of the matrix stack. 


Parameters: 


*m GLdouble or GLfloat: This array represents a 4x4 matrix that will be 
multiplied by the current matrix. The array is stored in column-major 
order as 16 consecutive values. 


Reference 


Returns: None. 
See Also: glMatrixMode, glLoadIdentity, glLoadMatrix, glPushMatrix 


glMultTransposeMatrix 


Purpose: Allows a transposed 4x4 matrix to be multiplied onto the matrix stack. 
Include File: <gl.h> 
Variations: 


void MultTransposeMatrixf(GLfloat *m) ; 
void MultTransposeMatrixd(GLdouble *m); 


Description: OpenGL uses 4x4 matrices in a single one-dimensional column-major 
array. A row major ordered array, which is the transpose of the column 
major array, may be multiplied onto the stack using this function. This 
function takes the matrix, transposes it, and then multiplies a properly 
formatted array with the top of the current matrix stack. Some OpenGL 
libraries may not export this function, even if the implementation 
supports it. In this case, a pointer to this function may be obtained via 
the OpenGL extension mechanism. 


Parameters: 

*m GLfloat or GLdouble: 4x4 transposed matrix to be multiplied onto the 
current stack. 

Returns: None. 

See Also: glMultMatrix, glLoadTransposeMatrix 

glPopMatrix 

Purpose: Pops the current matrix off the matrix stack. 


Include File: <gl.h> 
Syntax: 
void glPopMatrix(void) ; 


Description: This function pops the last (topmost) matrix off the current matrix stack. 
This function is most often used to restore the previous condition of the 
current transformation matrix if it was saved with a call to glPushMatrix. 


Returns: None. 
See Also: glPushMatrix 
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glPushMatrix 

Purpose: Pushes the current matrix onto the matrix stack. 
Include File: <gl.h> 

Syntax: 


void glPushMatrix(void) ; 


Description: This function pushes the current matrix onto the current matrix stack. 
This function is most often used to save the current transformation 
matrix so that it can be restored later with a call to glPopMatrix. 


Returns: None. 

See Also: glPopMatrix 

glRotate 

Purpose: Rotates the current matrix by a rotation matrix. 


Include File: <gl.h> 
Variations: 


void glRotated(GLdouble angle, GlLdouble x, GLdouble y, GLdouble z); 
void glRotatef(GLfloat angle, GLfloat x, GLfloat y, GLfloat z); 


Description: This function multiplies the current matrix by a rotation matrix that 
performs a counterclockwise rotation around a directional vector that 
passes from the origin through the point (x,y,z). The newly rotated 
matrix becomes the current transformation matrix. 


Parameters: 

angle GLdouble or GLfloat: The angle of rotation in degrees. The angle 
produces a counterclockwise rotation. 

% Viz GLdouble or GLfloat: A direction vector from the origin that is used as 
the axis of rotation. 

Returns: None. 

See Also: glScale, glTranslate 

glScale 

Purpose: Multiplies the current matrix by a scaling matrix. 

Include File: <gl.h> 

Variations: 


void glScaled(GLdouble x, GlLdouble y, GLdouble z); 
void glScalef(GLfloat x, GLfloat y, GLfloat z); 


Description: 


Parameters: 
X,Y, Z 
Returns: 


See Also: 


glTranslate 


Purpose: 
Include File: 
Variations: 


Reference 


This function multiplies the current matrix by a scaling matrix. The 
newly scaled matrix becomes the current transformation matrix. 


GLdouble or GLfloat: Scale factors along the x-, y-, and z-axes. 
None. 
glRotate, glTranslate 


Multiplies the current matrix by a translation matrix. 
<gl.h> 


void glTranslated(GLdouble x, GLdouble y, GLdouble z); 
void glTranslatef(GLfloat x, GLfloat y, GLfloat 2); 


Description: 


Parameters: 
KeVez 
Returns: 
See Also: 


gluLookAt 


Purpose: 
Include File: 
Syntax: 


This function multiplies the current matrix by a translation matrix. The 
newly translated matrix becomes the current transformation matrix. 


GLdouble or GLfloat: The x, y, and z coordinates of a translation vector. 
None. 
glRotate, glScale 


Defines a viewing transformation. 
<glu.h> 


void gluLookAt(GLdouble eyex, GLdouble eyey, GLdouble eyez, GLdouble centerx, 
GLdouble centery, GLdouble centerz, GLdouble upx, GLdouble upy, GLdouble upz ); 


Description: 


Parameters: 
eyex, eyey, 
eyez 
centerx, 
centery, 
centerz 


upx, upy, upz 


Defines a viewing transformation based on the position of the eye, the 
position of the center of the scene, and a vector pointing up from the 
viewer's perspective. 


GLdouble: X, y, and z coordinates of the eye point. 


GLdouble: X, y, and z coordinates of the center of the scene being 
looked at. 


GLdouble: X, y, and z coordinates that specify the up vector. 
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Returns: 
See Also: 


gluOrtho2D 


Purpose: 


Include File: 


Syntax: 


None. 
glFrustum, gluPerspective 


Defines a two-dimensional orthographic projection. 
<glu.h> 


void gluOrtho2D(GLdouble left, GLdouble right, GLdouble bottom, GLdouble top); 


Description: 


Parameters: 


left, right 


This function defines a 2D orthographic projection matrix. This projec- 
tion matrix is equivalent to calling glOrtho with near and far set to 0 
and 1, respectively. 


GLdouble: Specifies the far-left and far-right clipping planes. 


bottom, top GLdouble: Specifies the top and bottom clipping planes. 
Returns: None. 

See Also: gl0rtho, gluPerspective 

gluPerspective 

Purpose: Defines a viewing perspective projection matrix. 
Include File: <glu.h> 

Syntax: 


void gluPerspective(GLdouble fovy, GLdouble aspect, GLdouble zNear, GLdouble zFar) ; 


Description: 


Parameters: 


fovy 
aspect 


zNear, zFar 


Returns: 
See Also: 


This function creates a matrix that describes a viewing frustum in world 
coordinates. The aspect ratio should match the aspect ratio of the view- 
port (specified with g1Viewport). The perspective division is based on the 
field-of-view angle and the distance to the near and far clipping planes. 


GLdouble: The field of view in degrees, in the y direction. 


GLdouble: The aspect ratio. This is used to determine the field of view in 
the x direction. The aspect ratio is x/y. 


GLdouble: The distance from the viewer to the near and far clipping 
plane. These values are always positive. 


None. 
glFrustum, gluOrtho2D 


CHAPTER 5 


Color, Materials, and Lighting: 
The Basics 


By Richard S. Wright, Jr. 


WHAT YOU’LL LEARN IN THIS CHAPTER: 


How To Functions You'll Use 

Specify a color in terms of RGB components glColor 

Set the shading model glShadeModel 

Set the lighting model glLightModel 

Set lighting parameters glLight 

Set material reflective properties glColorMaterial/giMaterial 
Use surface normals glNormal 


This is the chapter where 3D graphics really start to look interesting (unless you really dig 
wireframe models!), and it only gets better from here. You’ve been learning OpenGL from 
the ground up—how to put programs together and then how to assemble objects from 
primitives and manipulate them in 3D space. Until now, we’ve been laying the founda- 
tion, and you still can’t tell what the house is going to look like! To recoin a phrase, 
“Where's the beef?” 


To put it succinctly, the beef starts here. For most of the rest of this book, science takes a 
back seat and magic rules. According to Arthur C. Clarke, “Any sufficiently advanced tech- 
nology is indistinguishable from magic.” Of course, there is no real magic involved in 
color and lighting, but it sure can seem that way at times. If you want to dig into the 
“sufficiently advanced technology” (mathematics), see Appendix A, “Further Reading.” 


Another name for this chapter might be “Adding Realism to Your Scenes.” You see, there is 
more to an object’s color in the real world than just what color we might tell OpenGL to 
make it. In addition to having a color, objects can appear shiny or dull or can even glow 
with their own light. An object’s apparent color varies with bright or dim lighting, and 
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even the color of the light hitting an object makes a difference. An illuminated object can 
even be shaded across its surface when lit or viewed from an angle. 


What Is Color? 


First let’s talk a little bit about color itself. How is a color made in nature, and how do we 
see colors? Understanding color theory and how the human eye sees a color scene will 
lend some insight into how you create a color programmatically. (If color theory is old hat 
to you, you can probably skip this section.) 


Light as a Wave 


Color is simply a wavelength of light that is visible to the human eye. If you had any 
physics classes in school, you might remember something about light being both a wave 
and a particle. It is modeled as a wave that travels through space much like a ripple 
through a pond, and it is modeled as a particle, such as a raindrop falling to the ground. 
If this concept seems confusing, you know why most people don’t study quantum 
mechanics! 


The light you see from nearly any given source is actually a mixture of many different 
kinds of light. These kinds of light are identified by their wavelengths. The wavelength of 
light is measured as the distance between the peaks of the light wave, as illustrated in 
Figure 5.1. 


ining —3 


Paks cccgal 


FIGURE 5.1 How a wavelength of light is measured. 


Wavelengths of visible light range from 390 nanometers (one billionth of a meter) for 
violet light to 720 nanometers for red light; this range is commonly called the visible spec- 
trum. You’ve undoubtedly heard the terms ultraviolet and infrared; they represent light not 
visible to the naked eye, lying beyond the ends of the spectrum. You will recognize the 
spectrum as containing all the colors of the rainbow (see Figure $.2). 


Light as a Particle 

“Okay, Mr. Smart Brain,” you might ask. “If color is a wavelength of light and the only 
visible light is in this ‘rainbow’ thing, where is the brown for my Fig Newtons or the black 
for my coffee or even the white of this page?” We begin answering that question by telling 
you that black is not a color, nor is white. Actually, black is the absence of color, and 


What Is Color? 213 


white is an even combination of all the colors at once. That is, a white object reflects all 
wavelengths of colors evenly, and a black object absorbs all wavelengths evenly. 


390 nm 
FIGURE 5.2 The spectrum of visible light. 


As for the brown of those fig bars and the many other colors that you see, they are indeed 

colors. Actually, at the physical level, they are composite colors. They are made of varying 

amounts of the “pure” colors found in the spectrum. To understand how this concept 

works, think of light as a particle. Any given object when illuminated by a light source is 

struck by “billions and billions” (my apologies to the late Carl Sagan) of photons, or tiny 

light particles. Remembering our physics mumbo jumbo, each of these photons is also a 

wave, which has a wavelength and thus a specific color in the spectrum. wn 


All physical objects consist of atoms. The reflection of photons from an object depends on 
the kinds of atoms, the number of each kind, and the arrangement of atoms (and their 
electrons) in the object. Some photons are reflected and some are absorbed (the absorbed 
photons are usually converted to heat), and any given material or mixture of materials 
(such as your fig bar) reflects more of some wavelengths than others. Figure 5.3 illustrates 
this principle. 


FIGURE 5.3 An object reflects some photons and absorbs others. 
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Your Personal Photon Detector 


The reflected light from your fig bar, when seen by your eye, is interpreted as color. The 
billions of photons enter your eye and are focused onto the back of your eye, where your 
retina acts as sort of a photographic plate. The retina’s millions of cone cells are excited 
when struck by the photons, and this causes neural energy to travel to your brain, which 
interprets the information as light and color. The more photons that strike the cone cells, 
the more excited they get. This level of excitation is interpreted by your brain as the 
brightness of the light, which makes sense; the brighter the light, the more photons there 
are to strike the cone cells. 


The eye has three kinds of cone cells. All of them respond to photons, but each kind 
responds most to a particular wavelength. One is more excited by photons that have 
reddish wavelengths; one, by green wavelengths; and one, by blue wavelengths. Thus, 
light that is composed mostly of red wavelengths excites red-sensitive cone cells more 
than the other cells, and your brain receives the signal that the light you are seeing is 
mostly reddish. You do the math: A combination of different wavelengths of various 
intensities will, of course, yield a mix of colors. All wavelengths equally represented thus 
are perceived as white, and no light of any wavelength is black. 


You can see that any “color” that your eye perceives actually consists of light all over the 
visible spectrum. The “hardware” in your eye detects what it sees in terms of the relative 
concentrations and strengths of red, green, and blue light. Figure 5.4 shows how brown is 
composed of a photon mix of 60% red photons, 40% green photons, and 10% blue 
photons. 


“Brown light” 
Eye lens 9 
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6 red, 4 green, and 1 blue photon 


FIGURE 5.4 How the “color” brown is perceived by the eye. 


The Computer as a Photon Generator 


Now that you understand how the human eye discerns colors, it makes sense that when 
you want to generate a color with a computer, you do so by specifying separate intensities 
for the red, green, and blue components of the light. It so happens that color computer 
monitors are designed to produce three kinds of light (can you guess which three?), each 
with varying degrees of intensity. In the back of your computer monitor is an electron gun 
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that shoots electrons at the back of the screen you view. This screen contains phosphors 
that emit red, green, and blue light when struck by the electrons. The intensity of the 
light emitted varies with the intensity of the electron beam. (Okay, then, how do color 
LCDs work? We leave this question as an exercise for you!) These three color phosphors 
are packed closely together to make up a single physical dot on the screen (see Figure 5.5). 


Electron gun 


Individual screen 
elements 


FIGURE 5.5 How a computer monitor generates colors. 


You might recall that in Chapter 2, “Using OpenGL,” we explained how OpenGL defines a 
color exactly as intensities of red, green, and blue, with the g1Color command. 


PC Color Hardware 


There once was a time when state-of-the-art PC graphics hardware meant the Hercules 
graphics card. This card could produce bitmapped images with a resolution of 720x348. 
The drawback was that each pixel had only two states: on and off. At that time, bitmapped 
graphics of any kind on a PC were a big deal, and you could produce some great mono- 
chrome graphics—even 3D! 


Actually predating the Hercules card was the Color Graphics Adapter (CGA) card. 
Introduced with the first IBM PC, this card could support resolutions of 320x200 pixels 
and could place any 4 of 16 colors on the screen at once. A higher resolution (640x200) 
with 2 colors was also possible but wasn’t as effective or cost conscious as the Hercules 
card. (Color monitors = $$$.) CGA was puny by today’s standards; it was even outmatched 
by the graphics capabilities of a $200 Commodore 64 or Atari home computer at the time. 
Lacking adequate resolution for business graphics or even modest modeling, CGA was 
used primarily for simple PC games or business applications that could benefit from 
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colored text. Generally, it was hard to make a good business justification for this more 
expensive hardware. 


The next big breakthrough for PC graphics came when IBM introduced the Enhanced 
Graphics Adapter (EGA) card. This one could do more than 25 lines of colored text in new 
text modes, and for graphics, it could support 640x350-pixel bitmapped graphics in 16 
colors! Other technical improvements eliminated some flickering problems of the CGA 
ancestor and provided for better and smoother animation. Now arcade-style games, real 
business graphics, and even simple 3D graphics became not only possible but even reason- 
able on the PC. This advance was a giant move beyond CGA, but still PC graphics were in 
their infancy. 


The last mainstream PC graphics standard set by IBM was the VGA card (which stood for 
Vector Graphics Array rather than the commonly held Video Graphics Adapter). This card 
was significantly faster than the EGA; it could support 16 colors at a higher resolution 
(640x480) and 256 colors at a lower resolution of 320x200. These 256 colors were selected 
from a palette of more than 16 million possible colors. That’s when the floodgates opened 
for PC graphics. Near photo-realistic graphics became possible on PCs. Ray tracers, 3D 
games, and photo-editing software began to pop up in the PC market. 


IBM, as well, had a high-end graphics card—the 8514—for its “workstations.” This card 
could do 1,024x768 graphics at 256 colors. IBM thought this card would be used only by 
CAD and scientific applications! But one thing is certain about consumers: They always 
want more. It was this short-sightedness that cost IBM its role as standard setter in the PC 
graphics market. Other vendors began to ship “Super-VGA” cards that could display 
higher and higher resolutions, with more and more colors. First, we saw 800x600, then 
1,024x768 and even higher, with first 256 colors, and then 32,000, and 65,000. Today, 24- 
bit color cards can display 16 million colors at resolutions far greater than 1,024x768. 
Even entry-level Windows PCs sold today can support at least 16 million colors at resolu- 
tions of 1,024x768 or more. 


All this power makes for some really cool possibilities—photo-realistic 3D graphics, to 
name just one. When Microsoft ported OpenGL to the Windows platform, that move 
enabled creation of high-end graphics applications for PCs. Combine today’s fast proces- 
sors with 3D-graphics accelerated graphics cards, and you can get the kind of performance 
possible only a few years ago on $100,000 graphics workstations—for the cost of a Wal- 
Mart Christmas special! Today’s typical home machines are capable of sophisticated simu- 
lations, games, and more. Already the term virtual reality has become as antiquated as 
those old Buck Rogers rocket ships as we begin to take advanced 3D graphics for granted. 


PC Display Modes 


Microsoft Windows and the Apple Macintosh revolutionized the world of PC graphics in 
two respects. First, they created mainstream graphical operating environments that were 
adopted by the business world at large and, soon thereafter, the consumer market. Second, 


PC Display Modes 


they made PC graphics significantly easier for programmers to do. The graphics hardware 
was “virtualized” by display device drivers. Instead of having to write instructions directly 
to the video hardware, programmers today can write to a single API (such as OpenGL!), 
and the operating system handles the specifics of talking to the hardware. 


Screen Resolution 


Screen resolution for today’s computers can vary from 640x480 pixels up to 1,600x1,200 
or more. The lower resolutions of, say, 640x480 are considered adequate for some graphics 
display tasks, and people with eye problems often run at the lower resolutions, but on a 
large monitor or display. You must always take into account the size of the window with 
the clipping volume and viewport settings (see Chapter 2). By scaling the size of the 
drawing to the size of the window, you can easily account for the various resolutions and 
window size combinations that can occur. Well-written graphics applications display the 
same approximate image regardless of screen resolution. The user should automatically be 
able to see more and sharper details as the resolution increases. 


Color Depth 


If an increase in screen resolution or in the number of available drawing pixels in turn 
increases the detail and sharpness of the image, so too should an increase in available 
colors improve the clarity of the resulting image. An image displayed on a computer that 
can display millions of colors should look remarkably better than the same image 
displayed with only 16 colors. In programming, you really need to worry about only three 
color depths: 4-bit, 8-bit, and 24-bit. 


The 4-Bit Color Mode 

On the low end, your program might run in 16 colors—called 4-bit mode because 4 bits 
are devoted to color information for each pixel. These 4 bits represent a value from 0 to 15 
that provides an index into a set of 16 predefined colors. (When you have a limited 
number of colors that are accessed by an index, this is called a palette.) With only 16 
colors at your disposal, you can do little to improve the clarity and sharpness of your 
image. It is generally accepted that most serious graphics applications can safely ignore the 
16-color mode. We can be thankful that most of the newer display hardware available 
does not support this display mode any longer. 


The 8-Bit Color Mode 

The 8-bit color mode supports up to 256 colors on the screen. This is a substantial 
improvement over 4-bit color, but still limiting. Most PC OpenGL hardware accelerators 
do not accelerate 8-bit color, but for software rendering, you can obtain satisfactory results 
under Windows with certain considerations. The most important consideration is the 
construction of the correct color palette. This topic is covered briefly in Chapter 13, 
“Wiggle: OpenGL on Windows.” 
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The 24-Bit Color Mode 

The best quality image production available today on PCs is 24-bit color mode. In this 
mode, a full 24 bits are devoted to each pixel to hold 8 bits of color data for each of the 
red, green, and blue color components (8 + 8 + 8 = 24). You have the capability to put any 
of more than 16 million possible colors in every pixel on the screen. The most obvious 
drawback to this mode is the amount of memory required for high-resolution screens 
(more than 2MB for a 1,024x768 screen). Indirectly, moving larger chunks of memory 
around is also much slower when you're doing animation or just drawing on the screen. 
Fortunately, today’s accelerated graphics adapters are optimized for these types of opera- 
tions and are shipping with larger amounts of onboard memory to accommodate the extra 
memory usage. 


The 16- and 32-Bit Color Modes 

For saving memory or improving performance, many display cards also support various 
other color modes. In the area of performance improvement, some cards support a 32-bit 
color mode sometimes called true color mode. Actually, the 32-bit color mode cannot 
display any more colors than the 24-bit mode, but it improves performance by aligning 
the data for each pixel on a 32-bit address boundary. Unfortunately, this results in a 
wasted 8 bits (1 byte) per pixel. On today’s 32-bit Intel PCs, a memory address evenly 
divisible by 32 results in much faster memory access. Modern OpenGL accelerators also 
support 32-bit mode, with 24 bits being reserved for the RGB colors and 8 bits being used 
for destination alpha storage. You will learn more about the alpha channel in the next 
chapter. 


Another popular display mode, 16-bit color, is sometimes supported to use memory more 
efficiently. This allows one of 65,536 possible colors for each pixel. This display mode is 
practically as effective as 24-bit color for photographic image reproduction, as it can be 
difficult to tell the difference between 16-bit and 24-bit color modes for most photo- 
graphic images. The savings in memory and increase in display speed have made this 
popular for the first generation of consumer “game” 3D accelerators. The added color 
fidelity of 24-bit mode, however, really adds to an image’s quality, especially with shading 
and blending operations. 


Using Color in OpenGL 


You now know that OpenGL specifies an exact color as separate intensities of red, green, 
and blue components. You also know that modern PC hardware might be able to display 
nearly all these combinations or only a very few. How, then, do we specify a desired color 
in terms of these red, green, and blue components? 


The Color Cube 


Because a color is specified by three positive color values, we can model the available 
colors as a volume that we call the RGB colorspace. Figure 5.6 shows what this colorspace 
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looks like at the origin with red, green, and blue as the axes. The red, green, and blue 
coordinates are specified just like x, y, and z coordinates. At the origin (0,0,0), the relative 
intensity of each component is zero, and the resulting color is black. The maximum avail- 
able on the PC for storage information is 24 bits, so with 8 bits for each component, let’s 
say that a value of 255 along the axis represents full saturation of that component. We 
then end up with a cube measuring 255 on each side. The corner directly opposite black, 
where the concentrations are (0,0,0), is white, with relative concentrations of 
(255,255,255). At full saturation (255) from the origin along each axis lies the pure colors 
of red, green, and blue. 


Blue 


FIGURE 5.6 The origin of RGB colorspace. 


This “color cube” (see Figure 5.7) contains all the possible colors, either on the surface of 
the cube or within the interior of the cube. For example, all possible shades of gray 
between black and white lie internally on the diagonal line between the corner at (0,0,0) 
and (255,255,255). 


Green Yellow 
(0,255,0) (255,255,0) 


Blue 


FIGURE 5.7 The RGB colorspace. 
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Figure 5.8 shows the smoothly shaded color cube produced by a sample program from this 
chapter, CCUBE. The surface of this cube shows the color variations from black on one 
corner to white on the opposite corner. Red, green, and blue are present on their corners 
255 units from black. Additionally, the colors yellow, cyan, and magenta have corners 
showing the combination of the other three primary colors. You can also spin the color 
cube around to examine all its sides by pressing the arrow keys. 


+ RGB Cube 


FIGURE 5.8 Output from CCUBE is this color cube. 


Setting the Drawing Color 
Let’s briefly review the g1Color function. It is prototyped as follows: 


void glColor<x><t>(red, green, blue, alpha); 


In the function name, the <x> represents the number of arguments; it might be 3 for three 
arguments of red, green, and blue or 4 for four arguments to include the alpha compo- 
nent. The alpha component specifies the translucency of the color and is covered in more 
detail in the next chapter. For now, just use a three-argument version of the function. 


The <t> in the function name specifies the argument’s data type and can be b, d, f, i, s, 
ub, ui, or us, for byte, double, float, integer, short, unsigned byte, unsigned integer, and 
unsigned short data types, respectively. Another version of the function has a v appended 
to the end; this version takes an array that contains the arguments (the v stands for 
vectored). In the reference section, you will find an entry with more details on the 
glColor function. 


Most OpenGL programs that you'll see use glColor3f and specify the intensity of each 
component as 0.0 for none or 1.0 for full intensity. However, it might be easier, if you 
have Windows programming experience, to use the g1Color3ub version of the function. 
This version takes three unsigned bytes, from 0 to 255, to specify the intensities of red, 


green, and blue. Using this version of the function is like using the Windows RGB macro 
to specify a color: 


glColor3ub(@,255,128) = RGB(0,255, 128) 


In fact, this approach might make it easier for you to match your OpenGL colors to exist- 
ing RGB colors used by your program for other non-OpenGL drawing tasks. However, we 
should say that, internally, OpenGL represents color values as floating-point values, and 
you may incur some performance penalties due to the constant conversion to floats that 
must take place at runtime. It is also possible that in the future, higher resolution color 
buffers may evolve (in fact, floating-point color buffers are already starting to appear), and 
your color values specified as floats will be more faithfully represented by the color hard- 
ware. 


Shading 


Our previous working definition for g1Color was that this function sets the current 
drawing color, and all objects drawn after this command have the last color specified. 
After discussing the OpenGL drawing primitives in the preceding chapter, we can now 
expand this definition as follows: The g1Color function sets the current color that is used 
for all vertices drawn after the command. So far, all our examples have drawn wireframe 
objects or solid objects with each face a different solid color. If we specify a different color 
for each vertex of a primitive (either point, line, or polygon), what color is the interior? 


Let’s answer this question first regarding points. A point has only one vertex, and what- 
ever color you specify for that vertex is the resulting color for that point. Easy enough. 


A line, however, has two vertices, and each can be set to a different color. The color of the 
line depends on the shading model. Shading is simply defined as the smooth transition 
from one color to the next. Any two points in the RGB colorspace (refer to Figure 5.7) can 
be connected by a straight line. 


Smooth shading causes the colors along the line to vary as they do through the color cube 
from one color point to the other. Figure 5.9 shows the color cube with the black and 
white corners identified. Below it is a line with two vertices, one black and one white. The 
colors selected along the length of the line match the colors along the straight line in the 
color cube, from the black to the white corners. This results in a line that progresses from 
black through lighter shades of gray and eventually to white. 


You can do shading mathematically by finding the equation of the line connecting two 
points in the three-dimensional RGB colorspace. Then you can simply loop through from 
one end of the line to the other, retrieving coordinates along the way to provide the color 
of each pixel on the screen. Many good books on computer graphics explain the algo- 
rithm to accomplish this effect, scale your color line to the physical line on the screen, 
and so on. Fortunately, OpenGL does all this work for you! 
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FIGURE 5.9 How a line is shaded from black to white. 


The shading exercise becomes slightly more complex for polygons. A triangle, for instance, 
can also be represented as a plane within the color cube. Figure 5.10 shows a triangle with 
each vertex at full saturation for the red, green, and blue color components. The code to 
display this triangle is shown in Listing 5.1 and in the sample program titled TRIANGLE 
on the CD that accompanies this book. 


Blue 


FIGURE 5.10 A triangle in RGB colorspace. 


Using Color in OpenGL 


LISTING 5.1 Drawing a Smooth-Shaded Triangle with Red, Green, and Blue Corners 


// Enable smooth shading 
glShadeModel(GL_SMOOTH) ; 


// Draw the triangle 

g1Begin(GL_TRIANGLES) ; 
// Red Apex 
glColor3ub((GLubyte) 255, (GLubyte)@, (GLubyte)®Q) ; 
glVertex3f (0.0f ,200.0f ,0.0Ff) ; 


// Green on the right bottom corner 
glColor3ub((GLubyte)0, (GLubyte) 255, (GLubyte) Q) ; 
glVertex3f (200.0f , -70.0f ,0.0f); 


// Blue on the left bottom corner 
glColor3ub((GLubyte)®, (GLubyte)@, (GLubyte) 255) ; 
glVertex3f(-200.0f, -70.0f, 0.0f); 

glEnd(); 


Setting the Shading Model 

The first line of Listing 5.1 actually sets the shading model OpenGL uses to do smooth 
shading—the model we have been discussing. This is the default shading model, but it’s a 
good idea to call this function anyway to ensure that your program is operating the way 
you intended. 


The other shading model that can be specified with g1ShadeModel is GL_FLAT for flat 
shading. Flat shading means that no shading calculations are performed on the interior of 
primitives. Generally, with flat shading, the color of the primitive’s interior is the color 
that was specified for the last vertex. The only exception is for a GL_POLYGON primitive, in 
which case the color is that of the first vertex. 


Next, the code in Listing 5.1 sets the top of the triangle to be pure red, the lower-right 
corner to be green, and the remaining bottom-left corner to be blue. Because smooth 
shading is specified, the interior of the triangle is shaded to provide a smooth transition 
between each corner. 


The output from the TRIANGLE program is shown in Figure 5.11. This output represents 
the plane shown graphically in Figure 5.10. 


Polygons, more complex than triangles, can also have different colors specified for each 
vertex. In these instances, the underlying logic for shading can become more intricate. 
Fortunately, you never have to worry about it with OpenGL. No matter how complex your 
polygon, OpenGL successfully shades the interior points between each vertex. 
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? RGB Triangle 


FIGURE 5.11 Output from the TRIANGLE program. 


Color in the Real World 


Real objects don’t appear in a solid or shaded color based solely on their RGB values. 
Figure 5.12 shows the output from the program titled JET from the CD. It’s a simple jet 
airplane, hand plotted with triangles using only the methods covered so far in this book. 
As usual, jet and the other programs in this chapter allow you to spin the object around 
by using the arrow keys to better see the effects. 


FIGURE 5.12 A simple jet built by setting a different color for each triangle. 


The selection of colors is meant to highlight the three-dimensional structure of the jet. 
Aside from the crude assemblage of triangles, however, you can see that the jet looks 
hardly anything like a real object. Suppose you constructed a model of this airplane and 
painted each flat surface the colors represented. The model would still appear glossy or flat 


Color in the Real World 


depending on the kind of paint used, and the color of each flat surface would vary with 
the angle of your view and any sources of light. 


OpenGL does a reasonably good job of approximating the real world in terms of lighting 
conditions. Unless an object emits its own light, it is illuminated by three different kinds 
of light: ambient, diffuse, and specular. 


Ambient Light 

Ambient light doesn’t come from any particular direction. It has a source, but the rays of 
light have bounced around the room or scene and become directionless. Objects illumi- 
nated by ambient light are evenly lit on all surfaces in all directions. You can think of all 
previous examples in this book as being lit by a bright ambient light because the objects 
were always visible and evenly colored (or shaded) regardless of their rotation or viewing 
angle. Figure 5.13 shows an object illuminated by ambient light. 
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FIGURE 5.13 An object illuminated purely by ambient light. 


Diffuse Light 

Diffuse light comes from a particular direction but is reflected evenly off a surface. Even 
though the light is reflected evenly, the object surface is brighter if the light is pointed 
directly at the surface than if the light grazes the surface from an angle. A good example of 
a diffuse light source is fluorescent lighting or sunlight streaming in a side window at 
noon. In Figure 5.14, the object is illuminated by a diffuse light source. 


Diffuse Light Source 


Light is scattered evenly 


FIGURE 5.14 An object illuminated by a purely diffuse light source. 
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Specular Light 

Like light comes from a particular direction but is reflected evenly off diffuse light, specu- 
lar light is directional, but it is reflected sharply and in a particular direction. A highly 
specular light tends to cause a bright spot on the surface it shines upon, which is called 
the specular highlight. A spotlight and the sun are examples of specular light. Figure 5.15 
shows an object illuminated by a purely specular light source. 


Specular Light Source 


Light is reflected 
sharply and uniformly 


FIGURE 5.15 An object illuminated by a purely specular light source. 


Putting It All Together 


No single light source is composed entirely of any of the three types of light just described. 
Rather, it is made up of varying intensities of each. For example, a red laser beam in a lab 
is composed of almost a pure-red specular component. However, smoke or dust particles 
scatter the beam, so it can be seen traveling across the room. This scattering represents the 
diffuse component of the light. If the beam is bright and no other light sources are 
present, you notice objects in the room taking on a red hue. This is a very small ambient 
component of that light. 


Thus, a light source in a scene is said to be composed of three lighting components: 
ambient, diffuse, and specular. Just like the components of a color, each lighting compo- 
nent is defined with an RGBA value that describes the relative intensities of red, green, 
and blue light that make up that component. (For the purposes of light color, the alpha 
value is ignored.) For example, our red laser light might be described by the component 
values in Table 5.1. 


TABLE 5.1 Color and Light Distribution for a Red Laser Light Source 


Red Green Blue Alpha 
Specular 0.99 0.0 0.0 1.0 
Diffuse 0.10 0.0 0.0 1.0 


Ambient 0.05 0.0 0.0 1.0 
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Note that the red laser beam has no green or blue light. Also, note that specular, diffuse, 
and ambient light can each range in intensity from 0.0 to 1.0. You could interpret this 
table as saying that the red laser light in some scenes has a very high specular component, 
a small diffuse component, and a very small ambient component. Wherever it shines, you 
are probably going to see a reddish spot. Also, because of conditions (smoke, dust, and so 
on) in the room, the diffuse component allows you to see the beam traveling through the 
air. Finally, the ambient component—likely due to smoke or dust particles, as well— 
scatters a tiny bit of light all about the room. Ambient and diffuse components of light 
are frequently combined because they are so similar in nature. 


Materials in the Real World 


Light is only part of the equation. In the real world, objects do have a color of their own. 
Earlier in this chapter, we described the color of an object as defined by its reflected wave- 
lengths of light. A blue ball reflects mostly blue photons and absorbs most others. This 
assumes that the light shining on the ball has blue photons in it to be reflected and 
detected by the observer. Generally, most scenes in the real world are illuminated by a 
white light containing an even mixture of all the colors. Under white light, therefore, 
most objects appear in their proper or “natural” colors. However, this is not always so; put 
the blue ball in a dark room with only a yellow light, and the ball appears black to the 
viewer because all the yellow light is absorbed and there is no blue to be reflected. 


Material Properties 

When we use lighting, we do not describe polygons as having a particular color, but rather 
as consisting of materials that have certain reflective properties. Instead of saying that a 
polygon is red, we say that the polygon is made of a material that reflects mostly red light. 
We are still saying that the surface is red, but now we must also specify the material's 
reflective properties for ambient, diffuse, and specular light sources. A material might be 
shiny and reflect specular light very well, while absorbing most of the ambient or diffuse 
light. Conversely, a flat colored object might absorb all specular light and not look shiny 
under any circumstances. Another property to be specified is the emission property for 
objects that emit their own light, such as taillights or glow-in-the-dark watches. 


Adding Light to Materials 

Setting lighting and material properties to achieve the desired effect takes some practice. 
There are no color cubes or rules of thumb to give you quick and easy answers. This is the 
point at which analysis gives way to art, and science yields to magic. When drawing an 
object, OpenGL decides which color to use for each pixel in the object. That object has 
reflective “colors,” and the light source has “colors” of its own. How does OpenGL deter- 
mine which colors to use? Understanding these principles is not difficult, but it does take 
some simple grade-school multiplication. (See, that teacher told you you’d need it one 
day!) 
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Each vertex of your primitives is assigned an RGB color value based on the net effect of 
the ambient, diffuse, and specular illumination multiplied by the ambient, diffuse, and 
specular reflectance of the material properties. Because you make use of smooth shading 
between the vertices, the illusion of illumination is achieved. 


Calculating Ambient Light Effects 

To calculate ambient light effects, you first need to put away the notion of color and 
instead think only in terms of red, green, and blue intensities. For an ambient light source 
of half-intensity red, green, and blue components, you have an RGB value for that source 
of (0.5, 0.5, 0.5). If this ambient light illuminates an object with ambient reflective proper- 
ties specified in RGB terms of (0.5, 1.0, 0.5), the net “color” component from the ambient 
light is 


(0.5 * 0.5, 0.5 * 1.0, 0.5 * 0.5) = (0.25, 0.5, 0.25) 


This is the result of multiplying each of the ambient light source terms by each of the 
ambient material property terms (see Figure 5.16). 


Ambient Light Source 


R G B 
5 Intensity 5 Intensity .5 Intensity 


Material ambient “color” (.5,1,.5) 


FIGURE 5.16 Calculating the ambient color component of an object. 


Thus, the material color components actually determine the percentage of incident light 
that is reflected. In our example, the ambient light had a red component that was at one- 
half intensity, and the material ambient property of 0.5 specified that one half of that one- 
half intensity light was reflected. Half of a half is a fourth, or 0.25. 


Diffuse and Specular Effects 

Calculating ambient light is as simple as it gets. Diffuse light also has RGB intensities that 
interact in the same way with material properties. However, diffuse light is directional, and 
the intensity at the surface of the object varies depending on the angle between the 
surface and the light source, the distance to the light source, any attenuation factors 
(whether it is foggy between the light and surface), and so on. The same goes for specular 
light sources and intensities. The net effect in terms of RGB values is figured the same way 
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as for ambient light, with the intensity of the light source (adjusted for the angle of inci- 
dence) being multiplied by the material reflectance. Finally, all three RGB terms are added 
to yield a final color for the object. If any single color component is greater than 1.0, it is 
clamped to that value. (You can’t get more intense than full intensity!) 


Generally, the ambient and diffuse components of light sources and materials are the same 
and have the greatest effect in determining the color of the object. Specular light and 
material properties tend to be light gray or white. The specular component depends signif- 
icantly on the angle of incidence, and specular highlights on an object are usually white. 


Adding Light to a Scene 


This text might seem like a lot of theory to digest all of a sudden. Let’s slow down and 
start exploring some examples of the OpenGL code needed for lighting; this exploration 
will also help reinforce what you’ve just learned. We demonstrate some additional features 
and requirements of lighting in OpenGL. The next few examples build on our JET 
program. The initial version contains no lighting code and just draws triangles with 
hidden surface elimination (depth testing) enabled. When we’re done, the jet’s metallic 
surface will glisten in the sunlight as you rotate it with the arrow keys. 


Enabling the Lighting 
To tell OpenGL to use lighting calculations, call glEnable with the GL_LIGHTING 
parameter: 


glEnable(GL_LIGHTING) ; 


This call alone tells OpenGL to use material properties and lighting parameters in deter- 
mining the color for each vertex in your scene. However, without any specified material 
properties or lighting parameters, your object remains dark and unlit, as shown in Figure 
5.17. Look at the code for any of the JET-based sample programs, and you can see that we 
have called the function SetupRC right after creating the rendering context. This is the 
place where we do any initialization of lighting parameters. 


Setting Up the Lighting Model 

After you enable lighting calculations, the first thing you should do is set up the lighting 
model. The three parameters that affect the lighting model are set with the glLightModel 
function. 


The first lighting parameter used in our next example (the AMBIENT program) is 
GL_LIGHT_MODEL_AMBIENT. It lets you specify a global ambient light that illuminates all 
objects evenly from all sides. The following code specifies a bright white light: 


// Bright white light - full intensity RGB values 
GLfloat ambientLight[] = { 1.0f, 1.0f, 1.0f, 1.0f }; 
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// Enable lighting 
glEnable(GL_LIGHTING) ; 


// Set light model to use ambient light specified by ambientLight[] 
glLightModelfv(GL_LIGHT_MODEL_AMBIENT, ambientLight) ; 


} Lighted Jet 


FIGURE 5.17 An unlit jet reflects no light. 


The variation of glLightModel shown here, glLightModelfv, takes as its first parameter the 
lighting model parameter being modified or set and then an array of the RGBA values that 
make up the light. The default RGBA values of this global ambient light are (0.2, 0.2, 0.2, 
1.0), which is fairly dim. Other lighting model parameters allow you to determine whether 
the front, back, or both sides of polygons are illuminated and how the calculation of spec- 
ular lighting angles is performed. See the reference section at the end of the chapter for 
more information on these parameters. 


Setting Material Properties 

Now that we have an ambient light source, we need to set some material properties so that 
our polygons reflect light and we can see our jet. There are two ways to set material prop- 
erties. The first is to use the function glMaterial before specifying each polygon or set of 
polygons. Examine the following code fragment: 


Glfloat gray[] = { 0.75f, 0.75f, 0.75f, 1.0f }; 


glMaterialfv(GL_FRONT, GL_AMBIENT_AND DIFFUSE, gray); 
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glBegin(GL_TRIANGLES) ; 
glVertex3f(-15.0f,0.0f,30.0f); 
glVertex3f(0.0f, 15.0f, 30.0f); 
glVertex3f(0.0f, 0.0f, -56.0f); 
glEnd() ; 


The first parameter to g1Materialfv specifies whether the front, back, or both (GL_FRONT, 
GL_BACK, or GL_FRONT_AND_BACK) take on the material properties specified. The second 
parameter tells which properties are being set; in this instance, both the ambient and 
diffuse reflectances are set to the same values. The final parameter is an array containing 
the RGBA values that make up these properties. All primitives specified after the 
glMaterial call are affected by the last values set, until another call to g1Material is 
made. 


Under most circumstances, the ambient and diffuse components are the same, and unless 
you want specular highlights (sparkling, shiny spots), you don’t need to define specular 
reflective properties. Even so, it would still be quite tedious if we had to define an array for 
every color in our object and call glMaterial before each polygon or group of polygons. 


Now we are ready for the second and preferred way of setting material properties, called 
color tracking. With color tracking, you can tell OpenGL to set material properties by only 
calling glColor. To enable color tracking, call glEnable with the GL_COLOR_MATERIAL para- 
meter: 


glEnable(GL_COLOR_MATERIAL) ; 
Then the function glColorMaterial specifies the material parameters that follow the 


values set by g1Color. For example, to set the ambient and diffuse properties of the fronts 
of polygons to track the colors set by glColor, call 


glColorMaterial(GL_FRONT,GL_AMBIENT_AND DIFFUSE) ; 
The earlier code fragment setting material properties would then be as follows. This 


approach looks like more code, but it actually saves many lines of code and executes faster 
as the number of different colored polygons grows: 


// Enable color tracking 
glEnable(GL_COLOR_MATERIAL) ; 


// Front material ambient and diffuse colors track glColor 
glColorMaterial(GL_FRONT, GL_AMBIENT_AND_DIFFUSE) ; 


glcolor3f(®.75f, @.75f, 0.75f); 
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glBegin(GL_TRIANGLES) ; 
glVertex3f (-15.0f ,0.0f ,30.0f) ; 
glVertex3f(0.0f, 15.0f, 30.0f); 
glVertex3f(0.0f, 0.0f, -56.0F); 
glEnd(); 


Listing 5.2 contains the code we add with the SetupRC function to our jet example to set 
up a bright ambient light source and to set the material properties that allow the object to 
reflect light and be seen. We have also changed the colors of the jet so that each section is 
a different color rather than each polygon. The final output, shown in Figure 5.18, is not 
much different from the image before we had lighting. However, if we reduce the ambient 
light by half, we get the image shown in Figure 5.19. To reduce it by half, we set the 
ambient light RGBA values to the following: 


GLfloat ambientLight[] = { 0.5f, O.5f, O.5f, 1.0f }; 


You can see how we might reduce the ambient light in a scene to produce a dimmer 
image. This capability is useful for simulations in which dusk approaches gradually or 
when a more direct light source is blocked, as when an object is in the shadow of another, 
larger object. 


Ambient Light Jet 


FIGURE 5.18 Output from completed AMBIENT sample program. 


LISTING 5.2 Setup for Ambient Lighting Conditions 


// This function does any needed initialization on the rendering 
// context. Here it sets up and initializes the lighting for 
// the scene. 
void SetupRC() 
{ 


Adding Light to a Scene 233 


LISTING 5.2 Continued 


// Light values 
// Bright white light 
GLfloat ambientLight[] = { 1.0f, 1.0f, 1.0f, 1.0f }; 


glEnable(GL_DEPTH_TEST) ; // Hidden surface removal 
glEnable(GL_CULL_FACE) ; // Do not calculate inside of jet 
glFrontFace(GL_CCW) ; // Counterclockwise polygons face out 


// Lighting stuff 
glEnable(GL_LIGHTING) ; // Enable lighting 


// Set light model to use ambient light specified by ambientLight[ ] 
glLightModelfv(GL_LIGHT_MODEL_AMBIENT, ambientLight) ; 
glEnable(GL_COLOR_MATERIAL) ; // Enable material color tracking 


// Front material ambient and diffuse colors track glColor 
glColorMaterial(GL_FRONT,GL_AMBIENT_AND_ DIFFUSE) ; 


// Nice light blue background 
glClearColor(0.0f, 0.0f, 05.f,1.0f); 


} 


: Ambient Light Jet 


FIGURE 5.19 Output from the AMBIENT program when the light source is cut in half. 
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Using a Light Source 


Manipulating the ambient light has its uses, but for most applications attempting to 
model the real world, you must specify one or more specific sources of light. In addition 
to their intensities and colors, these sources have a location and/or a direction. The place- 
ment of these lights can dramatically affect the appearance of your scene. 


OpenGL supports at least eight independent light sources located anywhere in your scene 
or out of the viewing volume. You can locate a light source an infinite distance away and 
make its light rays parallel or make it a nearby light source radiating outward. You can also 
specify a spotlight with a specific cone of light radiating from it, as well as manipulate its 
characteristics. 


Which Way Is Up? 

When you specify a light source, you tell OpenGL where it is and in which direction it’s 
shining. Often, the light source shines in all directions, but it can be directional. Either 
way, for any object you draw, the rays of light from any source (other than a pure ambient 
source) strike the surface of the polygons that make up the object at an angle. Of course, 
in the case of a directional light, the surfaces of all polygons might not necessarily be illu- 
minated. To calculate the shading effects across the surface of the polygons, OpenGL must 
be able to calculate the angle. 


In Figure 5.20, a polygon (a square) is being struck by a ray of light from some source. The 
ray makes an angle (A) with the plane as it strikes the surface. The light is then reflected at 
an angle (B) toward the viewer (or you wouldn’t see it). These angles are used in conjunc- 
tion with the lighting and material properties we have discussed thus far to calculate the 
apparent color of that location. It happens by design that the locations used by OpenGL 
are the vertices of the polygon. Because OpenGL calculates the apparent colors for each 
vertex and then does smooth shading between them, the illusion of lighting is created. 


Magic! 
A Light source 
- Viewer 


FIGURE 5.20 Light is reflected off objects at specific angles. 


Using a Light Source 


From a programming standpoint, these lighting calculations present a slight conceptual 
difficulty. Each polygon is created as a set of vertices, which are nothing more than points. 
Each vertex is then struck by a ray of light at some angle. How then do you (or OpenGL) 
calculate the angle between a point and a line (the ray of light)? Of course, you can’t 
geometrically find the angle between a single point and a line in 3D space because there 
are an infinite number of possibilities. Therefore, you must associate with each vertex 
some piece of information that denotes a direction upward from the vertex and away from 
the surface of the primitive. 


Surface Normals 

A line from the vertex in the upward direction starts in some imaginary plane (or your 
polygon) at a right angle. This line is called a normal vector. The term normal vector might 
sound like something the Star Trek crew members toss around, but it just means a line 
perpendicular to a real or imaginary surface. A vector is a line pointed in some direction, 
and the word normal is just another way for eggheads to say perpendicular (intersecting at 
a 90° angle). As if the word perpendicular weren’t bad enough! Therefore, a normal vector is 
a line pointed in a direction that is at a 90° angle to the surface of your polygon. Figure 
5.21 presents examples of 2D and 3D normal vectors. 


Normal vector Normal vector 
90° 90° 
A 2D normal vector A 3D normal vector 


FIGURE 5.21 A 2D and a 3D normal vector. 


You might already be asking why we must specify a normal vector for each vertex. Why 
can’t we just specify a single normal for a polygon and use it for each vertex? We can— 
and for our first few examples, we do. However, sometimes you don’t want each normal to 
be exactly perpendicular to the surface of the polygon. You may have noticed that many 
surfaces are not flat! You can approximate these surfaces with flat, polygonal sections, but 
you end up with a jagged or multifaceted surface. Later, we discuss a technique to produce 
the illusion of smooth curves with flat polygons by “tweaking” surface normals (more 
magic!). But first things first... 


Specifying a Normal 
To see how we specify a normal for a vertex, let’s look at Figure 5.22—a plane floating 
above the xz plane in 3D space. We’ve made this illustration simple to demonstrate the 
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concept. Notice the line through the vertex (1,1,0) that is perpendicular to the plane. If we 
select any point on this line, say (1,10,0), the line from the first point (1,1,0) to the 
second point (1,10,0) is our normal vector. The second point specified actually indicates 
that the direction from the vertex is up in the y direction. This convention is also used to 
indicate the front and back sides of polygons, as the vector travels up and away from the 
front surface. 


Normal vector 


(1,10,0) 


FIGURE 5.22 A normal vector traveling perpendicular from the surface. 


You can see that this second point is the number of units in the x, y, and z directions for 
some point on the normal vector away from the vertex. Rather than specify two points for 
each normal vector, we can subtract the vertex from the second point on the normal, 
yielding a single coordinate triplet that indicates the x, y, and z steps away from the 
vertex. For our example, this is 


(1,10,0) - (1,1,0) = (1 - 1, 10 - 1, 0) = (0, 9, 0) 


Here’s another way of looking at this example: If the vertex were translated to the origin, 

the point specified by subtracting the two original points would still specify the direction 

pointing away and at a 90° angle from the surface. Figure 5.23 shows the newly translated 
normal vector. 


The vector is a directional quantity that tells OpenGL which direction the vertices (or 
polygon) face. This next code segment shows a normal vector being specified for one of 
the triangles in the JET sample program: 


g1Begin(GL_TRIANGLES) ; 
glNormal3f(0.0f, -1.0f, 0.0f); 
glVertex3f(0.0f, 0.0f, 60.0f); 
glVertex3f(-15.0f, 0.0f, 30.0f); 
glVertex3f (15.0f ,0.0f ,30.0f) ; 
glEnd(); 
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FIGURE 5.23 The newly translated normal vector. 


The function glNormal3f takes the coordinate triplet that specifies a normal vector point- 
ing in the direction perpendicular to the surface of this triangle. In this example, the 
normals for all three vertices have the same direction, which is down the negative y-axis. 
This is a simple example because the triangle is lying flat in the xz plane, and it actually 
represents a bottom section of the jet. You’ll see later that often we want to specify a 
different normal for each vertex. 


The prospect of specifying a normal for every vertex or polygon in your drawing might 
seem daunting, especially because few surfaces lie cleanly in one of the major planes. 
Never fear! We shortly present a reusable function that you can call again and again to 
calculate your normals for you. 


POLYGON WINDING 


Take special note of the order of the vertices in the jet’s triangle. If you view this triangle being 
drawn from the direction in which the normal vector points, the corners appear counterclockwise 
around the triangle. This is called polygon winding. By default, the front of a polygon is defined as 
the side from which the vertices appear to be wound in a counterclockwise fashion. 


Unit Normals 


As OpenGL does its magic, all surface normals must eventually be converted to unit 
normals. A unit normal is just a normal vector that has a length of 1. The normal in 
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Figure 5.23 has a length of 9. You can find the length of any normal by squaring each 
component, adding them together, and taking the square root. Divide each component of 
the normal by the length, and you get a vector pointed in exactly the same direction, but 
only 1 unit long. In this case, our new normal vector is specified as (0,1,0). This is called 
normalization. Thus, for lighting calculations, all normal vectors must be normalized. Talk 
about jargon! 


You can tell OpenGL to convert your normals to unit normals automatically, by enabling 
normalization with glEnable and a parameter of GL_NORMALIZE: 


glEnable(GL_NORMALIZE) ; 


This approach does, however, have performance penalties. It’s far better to calculate your 
normals ahead of time as unit normals instead of relying on OpenGL to perform this task 
for you. 


You should note that calls to the glScale transformation function also scale the length of 
your normals. If you use g1Scale and lighting, you can obtain undesired results from your 
OpenGL lighting. If you have specified unit normals for all your geometry and used a 
constant scaling factor with g1Scale (all geometry is scaled by the same amount), a new 
alternative to GL_NORMALIZE (new to OpenGL 1.2) is GL_RESCALE_NORMALS. You enable this 
parameter with a call such as 


glEnable(GL_RESCALE_NORMALS) ; 


This call tells OpenGL that your normals are not unit length, but they can all be scaled by 
the same amount to make them unit length. OpenGL figures this out by examining the 
modelview matrix. The result is fewer mathematical operations per vertex than are other- 
wise required. 


Because it is better to give OpenGL unit normals to begin with, the g1Tools library comes 
with a function that will take any normal vector and “normalize” it for you: 


void gltNormalizeVector(GLTVector vNormal) ; 


Finding a Normal 


Figure 5.24 presents another polygon that is not simply lying in one of the axis planes. 
The normal vector pointing away from this surface is more difficult to guess, so we need 
an easy way to calculate the normal for any arbitrary polygon in 3D coordinates. 


You can easily calculate the normal vector for any polygon by taking three points that lie 
in the plane of that polygon. Figure 5.25 shows three points—P1, P2, and P3—that you 
can use to define two vectors: vector V1 from P1 to P2, and vector V2 from P1 to P3. 
Mathematically, two vectors in three-dimensional space define a plane. (Your original 
polygon lies in this plane.) If you take the cross product of those two vectors (written 
mathematically as V1 X V2), the resulting vector is perpendicular to that plane. Figure 
5.26 shows the vector V3 derived by taking the cross product of V1 and V2. 
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FIGURE 5.24 A nontrivial normal problem. 
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FIGURE 5.25 Two vectors defined by three points on a plane. 


FIGURE 5.26 A normal vector as the cross product of two vectors. 
Again, because this is such a useful and often-used method, the g1Tools library contains a 
function that calculates a normal vector based on three points on a polygon: 


void gltGetNormalVector(GLTVector vP1, GLTVector vP2, 
GLTVector vP3, GLTVector vNormal); 
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To use this function, pass it three vectors (each just an array of three floats) from your 
polygon or triangle (specified in counterclockwise winding order) and another vector array 
that will contain the normal vector on return. 


Setting Up a Source 


Now that you understand the requirements of setting up your polygons to receive and 
interact with a light source, it’s time to turn on the lights! Listing 5.3 shows the SetupRC 
function from the sample program LITJET. Part of the setup process for this sample 
program creates a light source and places it to the upper left, slightly behind the viewer. 
The light source GL_LIGHT@ has its ambient and diffuse components set to the intensities 
specified by the arrays ambientLight[] and diffuseLight[]. This results in a moderate 
white light source: 


GLfloat ambientLight[] 
GLfloat diffuseLight[] 


{ 0.3f, 0.3f, 0.3f, 1.0f }; 
{ 0.7f, 0.7f, O.7f, 1.0f }; 


// Set up and enable light @ 
glLightfv(GL_LIGHTO,GL_AMBIENT, ambientLight) ; 
glLightfv(GL_LIGHT@,GL_DIFFUSE,diffuseLight) ; 


Finally, the light source GL_LIGHT® is enabled: 


glEnable(GL_LIGHT®) ; 


The light is positioned by this code, located in the ChangeSize function: 
GLfloat lightPos[] = { -50.f, 50.0f, 100.0f, 1.0f }; 


glLightfv(GL_LIGHT@,GL_POSITION, lightPos) ; 


Here, lightPos[] contains the position of the light. The last value in this array is 1.0, 
which specifies that the designated coordinates are the position of the light source. If the 
last value in the array is 0.0, it indicates that the light is an infinite distance away along 
the vector specified by this array. We touch more on this issue later. Lights are like 
geometric objects in that they can be moved around by the modelview matrix. By placing 
the light’s position when the viewing transformation is performed, we ensure the light is 
in the proper location regardless of how we transform the geometry. 
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LISTING 5.3 Light and Rendering Context Setup for LITJET 


// This function does any needed initialization on the rendering 
// context. Here it sets up and initializes the lighting for 
// the scene. 
void SetupRC() 
{ 
// Light values and coordinates 
GLfloat ambientLight[] = { 0.3f, 0.3f, @.3f, 1.0f }; 
GLfloat diffuseLight[] = { 0.7f, 0.7f, 0.7f, 1.Of }; 


glEnable(GL_DEPTH_TEST) ; // Hidden surface removal 
glFrontFace(GL_CCW) ; // Counterclockwise polygons face out 
glEnable(GL_CULL_FACE) ; // Do not calculate inside of jet 


// Enable lighting 
glEnable(GL_LIGHTING) ; 


// Set up and enable light 0 
glLightfv(GL_LIGHT@,GL_AMBIENT, ambientLight) ; 
glLightfv(GL_LIGHT®,GL_DIFFUSE,diffuseLight) ; 
glEnable(GL_LIGHT®O) ; 


// Enable color tracking 
glEnable(GL_COLOR_MATERIAL) ; 


// Set material properties to follow glColor values 
glColorMaterial(GL_FRONT, GL_AMBIENT_AND DIFFUSE) ; 


// Light blue background 
glClearColor(0.0f, 0.0f, 1.0f, 1.0f ); 
} 


Setting the Material Properties 

Notice in Listing 5.3 that color tracking is enabled, and the properties to be tracked are the 
ambient and diffuse reflective properties for the front surface of the polygons. This is just 
as it was defined in the AMBIENT sample program: 


// Enable color tracking 
glEnable(GL_COLOR_MATERIAL) ; 
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// Set material properties to follow glColor values 
glColorMaterial(GL_FRONT, GL_AMBIENT_AND_DIFFUSE) ; 


Specifying the Polygons 
The rendering code from the first two JET samples changes considerably now to support 
the new lighting model. Listing 5.4 is an excerpt taken from the RenderScene function 


from LITJET. 

LISTING 5.4 Code Sample That Sets Color and Calculates and Specifies Normals and 
Polygons 

GLTVector vNormal; // Storage for calculated surface normal 


// Set material color 

glColor3ub(128, 128, 128); 

glBegin(GL_TRIANGLES) ; 
glNormal3f(0.0f, -1.0f, 0.0f); 
glNormal3f(0.0f, -1.0f, 0.0f); 
glVertex3f(0.0f, 0.0f, 60.0f); 
glVertex3f(-15.0f, 0.0f, 30.0f); 
glVertex3f (15.0f ,0.0f ,30.0f) ; 


// Vertices for this panel 

{ 

GLTVector vPoints[3] = {{ 15.0f, 0.0f, 30.0f}, 
{ 0.0f, 15.0f, 30.0f}, 
{ 0.0f, 0.0f, 60.0f}}; 


// Calculate the normal for the plane 
gltGetNormalVector(vPoints[®], vPoints[1], vPoints[2], vNormal) ; 
glNormal3fv(vNormal) ; 

glVertex3fv(vPoints[Q]) ; 

glVertex3fv(vPoints[1]); 

glVertex3fv(vPoints[2]); 

} 


{ 
GLTVector vPoints[3] = {{ 0.0f, 0@.0f, 60.0f }, 
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LISTING 5.4 Continued 


{ 0.0f, 15.0fF, 30.0f }, 
{ -15.0f, 0.0f, 30.0f }}; 


gltGetNormalVector(vPoints[0], vPoints[1], vPoints[2], vNormal) ; 
glNormal3fv(vNormal) ; 

glVertex3fv(vPoints[®]); 

glVertex3fv(vPoints[1]); 

glVertex3fv(vPoints[2]); 

} 


Notice that we are calculating the normal vector using the gltGetNormalVector function 

from glTools. Also, the material properties are now following the colors set by g1Color. 

One other thing you notice is that not every triangle is blocked by g1Begin/glEnd func- 

tions. You can specify once that you are drawing triangles, and every three vertices are 

used for a new triangle until you specify otherwise with glEnd. For very large numbers of 

polygons, this technique can considerably boost performance by eliminating many unnec- 

essary function calls and primitive batch setup. wn 


Figure 5.27 shows the output from the completed LITJET sample program. The jet is now a 
single shade of gray instead of multiple colors. We changed the color to make it easier to 
see the lighting effects on the surface. Even though the plane is one solid “color,” you can 
still see the shape due to the lighting. By rotating the jet around with the arrow keys, you 
can see the dramatic shading effects as the surface of the jet moves and interacts with the 
light. 


Lighted Jet 


FIGURE 5.27 Output from the LITJET program. 
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TIP 

The most obvious way to improve the performance of this code is to calculate all the normal 
vectors ahead of time and store them for use in the RenderScene function. Before you pursue 
this, read Chapter 11, “It’s All About the Pipeline: Faster Geometry Throughput,” for the material 
on display lists and vertex arrays. Display lists and vertex arrays provide a means of storing calcu- 
lated values not only for the normal vectors, but for the polygon data as well. Remember, these 
examples are meant to demonstrate the concepts. They are not necessarily the most efficient 
code possible. 


Lighting Effects 


The ambient and diffuse lights from the LITJET example are sufficient to provide the illu- 
sion of lighting. The surface of the jet appears shaded according to the angle of the inci- 
dent light. As the jet rotates, these angles change and you can see the lighting effects 
changing in such a way that you can easily guess where the light is coming from. 


We ignored the specular component of the light source, however, as well as the specular 
reflectivity of the material properties on the jet. Although the lighting effects are 
pronounced, the surface of the jet is rather flatly colored. Ambient and diffuse lighting 
and material properties are all you need if you are modeling clay, wood, cardboard, cloth, 
or some other flatly colored object. But for metallic surfaces such as the skin of an 
airplane, some shine is often desirable. 


Specular Highlights 

Specular lighting and material properties add needed gloss to the surface of your objects. 
This shininess has a whitening effect on an object’s color and can produce specular high- 
lights when the angle of incident light is sharp in relation to the viewer. A specular high- 
light is what occurs when nearly all the light striking the surface of an object is reflected 
away. The white sparkle on a shiny red ball in the sunlight is a good example of a specular 
highlight. 


Specular Light 

You can easily add a specular component to a light source. The following code shows the 
light source setup for the LITJET program, modified to add a specular component to the 
light: 


// Light values and coordinates 

GLfloat ambientLight[] = { 0.3f, 0.3f, 0.3f, 1.0f }; 
GLfloat diffuseLight[] = { 0.7f, 0.7f, 0.7f, 1.0f }; 
GLfloat specular[] = { 1.0f, 1.0f, 1.0f, 1.0f}; 


Lighting Effects 


// Enable lighting 
glEnable(GL_LIGHTING) ; 


// Set up and enable light 0 
glLightfv(GL_LIGHT@,GL_AMBIENT, ambientLight) ; 
glLightfv(GL_LIGHT@,GL_DIFFUSE ,diffuseLight) ; 
glLightfv(GL_LIGHTO,GL_SPECULAR, specular) ; 
glEnable(GL_LIGHT®) ; 


The specular[] array specifies a very bright white light source for the specular component 
of the light. Our purpose here is to model bright sunlight. The following line simply adds 
this specular component to the light source GL_LIGHTO: 


glLightfv(GL_LIGHTO,GL_SPECULAR, specular) ; 


If this were the only change you made to LITJET, you wouldn’t see any difference in the 
jet’s appearance. We haven’t yet defined any specular reflectance properties for the mater- 
ial properties. 


Specular Reflectance 

Adding specular reflectance to material properties is just as easy as adding the specular 
component to the light source. This next code segment shows the code from LITJET, again 
modified to add specular reflectance to the material properties: 


// Light values and coordinates 
GLfloat specref[] = { 1.0f, 1.0f, 1.0f, 1.0f }; 


// Enable color tracking 
glEnable(GL_COLOR_MATERIAL) ; 


// Set material properties to follow glColor values 
glColorMaterial(GL_FRONT, GL_AMBIENT_AND DIFFUSE) ; 


// All materials hereafter have full specular reflectivity 
// with a high shine 

glMaterialfv(GL_FRONT, GL_SPECULAR, specref) ; 
glMateriali(GL_FRONT,GL_SHININESS, 128) ; 
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As before, we enable color tracking so that the ambient and diffuse reflectance of the 
materials follow the current color set by the glColor functions. (Of course, we don’t want 
the specular reflectance to track glColor because we are specifying it separately and it 
doesn’t change.) 


Now, we’ve added the array specref[], which contains the RGBA values for our specular 
reflectance. This array of all 1s produces a surface that reflects nearly all incident specular 
light. The following line sets the material properties for all subsequent polygons to have 
this reflectance: 


glMaterialfv(GL_FRONT, GL_SPECULAR,specref) ; 


Because we do not call g1Material again with the GL_SPECULAR property, all materials have 
this property. We set up the example this way on purpose because we want the entire jet 
to appear made of metal or very shiny composites. 


What we have done here in our setup routine is important: We have specified that the 
ambient and diffuse reflective material properties of all future polygons (until we say 
otherwise with another call to glMaterial or glColorMaterial) change as the current 
color changes, but that the specular reflective properties remain the same. 


Specular Exponent 


As stated earlier, high specular light and reflectivity brighten the colors of the object. For 
this example, the present extremely high specular light (full intensity) and specular reflec- 
tivity (full reflectivity) result in a jet that appears almost totally white or gray except 
where the surface points away from the light source (in which case, it is black and unlit). 
To temper this effect, we use the next line of code after the specular component is speci- 
fied: 


glMateriali(GL_FRONT,GL_SHININESS, 128) ; 


The GL_SHININESS property sets the specular exponent of the material, which specifies 
how small and focused the specular highlight is. A value of 0 specifies an unfocused specu- 
lar highlight, which is actually what is producing the brightening of the colors evenly 
across the entire polygon. If you set this value, you reduce the size and increase the focus 
of the specular highlight, causing a shiny spot to appear. The larger the value, the more 
shiny and pronounced the surface. The range of this parameter is 1-128 for all implemen- 
tations of OpenGL. 


Listing 5.5 shows the new SetupRC code in the sample program SHINYJET. This is the only 
code that has changed from LITJET (other than the title of the window) to produce a very 
shiny and glistening jet. Figure 5.28 shows the output from this program, but to fully 
appreciate the effect, you should run the program and hold down one of the arrow keys to 
spin the jet about in the sunlight. 
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+ Shiny Jet 


FIGURE 5.28 Output from the SHINYJET program. 


LISTING 5.5 Setup from SHINYJET to Produce Specular Highlights on the Jet 


// This function does any needed initialization on the rendering 
// context. Here it sets up and initializes the lighting for mn 
// the scene. 
void SetupRC() 
{ 
// Light values and coordinates 
GLfloat ambientLight[] { O.9f, 0.37, 023f, 1.0 33 
GLfloat diffuseLight[] = { 0.7f, 0.7f, 0.7f, 1.0f }; 
GLfloat specular[] = { 1.0f, 1.0f, 1.0f, 1.Of}; 
GLfloat specref[] = { 1.0f, 1.0f, 1.0f, 1.0f }; 


alk Polk 


glEnable(GL_DEPTH_TEST) ; // Hidden surface removal 
glFrontFace(GL_CCW) ; // Counterclockwise polygons face out 
glEnable(GL_CULL_FACE) ; // Do not calculate inside of jet 


// Enable lighting 
glEnable(GL_LIGHTING) ; 


// Set up and enable light 0 
glLightfv(GL_LIGHT@,GL_AMBIENT,ambientLight) ; 
glLightfv(GL_LIGHT®,GL_DIFFUSE,diffuseLight) ; 
glLightfv(GL_LIGHT@,GL_SPECULAR, specular) ; 
glEnable(GL_LIGHT®) ; 
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LISTING 5.5 Continued 


// Enable color tracking 
glEnable(GL_COLOR_MATERIAL) ; 


// Set material properties to follow glColor values 
glColorMaterial(GL_FRONT, GL_AMBIENT_AND_ DIFFUSE) ; 


// All materials hereafter have full specular reflectivity 
// with a high shine 

glMaterialfv(GL_FRONT, GL_SPECULAR, specref) ; 
glMateriali(GL_FRONT,GL_SHININESS, 128) ; 


// Light blue background 
glClearColor(0.0f, 0.0f, 1.0f, 1.0f ); 
} 


Normal Averaging 

Earlier, we mentioned that by “tweaking” your normals, you can produce apparently 
smooth surfaces with flat polygons. This technique, known as normal averaging, produces 
some interesting optical illusions. Say you have a sphere made up of quads and triangles 
like the one shown in Figure 5.29. 
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FIGURE 5.29 A typical sphere made up of quads and triangles. 


Lighting Effects 


If each face of the sphere had a single normal specified, the sphere would look like a large 
faceted jewel. If you specify the “true” normal for each vertex, however, the lighting calcu- 
lations at each vertex produce values that OpenGL smoothly interpolates across the face of 
the polygon. Thus, the flat polygons are shaded as if they were a smooth surface. 


What do we mean by “true” normal? The polygonal representation is only an approxima- 
tion of the true surface. Theoretically, if we used enough polygons, the surface would 
appear smooth. This is similar to the idea we used in Chapter 3, “Drawing in Space: 
Geometric Primitives and Buffers,” to draw a smooth curve with a series of short line 
segments. If we consider each vertex to be a point on the true surface, the actual normal 
value for that surface is the true normal for the surface. 


For our case of the sphere, the normal would point directly out from the center of the 
sphere through each vertex. We show this graphically for a simple 2D case in Figures 5.30 
and 5.31. In Figure 5.30, each flat segment has a normal pointing perpendicular to its 
surface. We did this just like we did for our LITJET example previously. Figure 5.31, 
however, shows how each normal is not perpendicular to the line segment but is perpen- 
dicular to the surface of the sphere, or the tangent line to the surface. 


FIGURE 5.30 An approximation with normals perpendicular to each face. 


The tangent line touches the curve in one place and does not penetrate it. The 3D equiva- 
lent is a tangent plane. In Figure 5.31, you can see the outline of the actual surface and 
that the normal is actually perpendicular to the line tangent to the surface. 


For a sphere, calculation of the normal is reasonably simple. (The normal actually has the 
same values as the vertex relative to the center!) For other nontrivial surfaces, the calcula- 
tion might not be so easy. In such cases, you calculate the normals for each polygon that 
shared a vertex. The actual normal you assign to that vertex is the average of these 
normals. The visual effect is a nice, smooth, regular surface, even though it is actually 
composed of numerous small, flat segments. 
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Approximation 
of surface 


FIGURE 5.31 Each normal is perpendicular to the surface itself. 


Putting It All Together 


Now it’s time for a more complex sample program. We demonstrate how to use normals to 
create a smooth surface appearance, move a light around in a scene, create a spot light, 
and finally, identify one of the drawbacks of OpenGL lighting. 


Our next sample program, SPOT, performs all these tasks. Here, we create a solid sphere in 
the center of our viewing volume with glutSolidSphere. We shine a spotlight on this 
sphere that we can move around, and we change the “smoothness” of the normals and 
demonstrate some of the limitations of OpenGL lighting. 


So far, we have been specifying a light’s position with glLight as follows: 


// Array to specify position 
GLfloat lightPos[] = { 0.O0f, 150.0f, 150.0f, 1.0f }; 


// Set the light position 
glLightfv(GL_LIGHT@,GL_POSITION, lightPos) ; 


The array lightPos[] contains the x, y, and z values that specify either the light’s actual 
position in the scene or the direction from which the light is coming. The last value, 1.0 
in this case, indicates that the light is actually present at this location. By default, the light 
radiates equally in all directions from this location, but you can change this default to 
make a spotlight effect. 
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To make a light source an infinite distance away and coming from the direction specified 
by this vector, you place 0.0 in this last lightPos[] array element. A directional light 
source, as this is called, strikes the surface of your objects evenly. That is, all the light rays 
are parallel. In a positional light source, on the other hand, the light rays diverge from the 
light source. 


Creating a Spotlight 

Creating a spotlight is no different from creating any other positional light source. The 
code in Listing 5.6 shows the SetupRC function from the SPOT sample program. This 
program places a blue sphere in the center of the window. It also creates a spotlight that 
you can move vertically with the up- and down-arrow keys and horizontally with the left- 
and right-arrow keys. As the spotlight moves over the surface of the sphere, a specular 
highlight follows it on the surface. 


LISTING 5.6 Lighting Setup for the SPOT Sample Program 


// Light values and coordinates 

GLfloat lightPos[] = { 0.0f, @.0f, 75.0f, 1.O0f }; 
GLfloat specular[] = { 1.0f, 1.0f, 1.0f, 1.0f}; 
GLfloat specref[] = { 1.0f, 1.0f, 1.0f, 1.0f }; 
GLfloat ambientLight[] = { 0.5f, 0.5f, O.5f, 1.O0f}; 
GLfloat spotDir[] = { 0.0f, @.Of, -1.0f }; 


// This function does any needed initialization on the rendering 
// context. Here it sets up and initializes the lighting for 

// the scene. 

void SetupRC() 


{ 

glEnable(GL_DEPTH_TEST) ; // Hidden surface removal 
glFrontFace(GL_CCW) ; // Counterclockwise polygons face out 
glEnable(GL_CULL_FACE) ; // Do not try to display the back sides 


// Enable lighting 
glEnable(GL_LIGHTING) ; 


// Set up and enable light 0 
// Supply a slight ambient light so the objects can be seen 
glLightModelfv(GL_LIGHT MODEL_AMBIENT, ambientLight) ; 


// The light is composed of just diffuse and specular components 
glLightfv(GL_LIGHT®,GL_DIFFUSE,ambientLight) ; 
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LISTING 5.6 Continued 


glLightfv(GL_LIGHTO,GL_SPECULAR, specular) ; 
glLightfv(GL_LIGHT@,GL_POSITION, lightPos) ; 


// Specific spot effects 
// Cut off angle is 60 degrees 
glLightf(GL_LIGHTO,GL_SPOT_CUTOFF ,60.0f) ; 


// Enable this light in particular 
glEnable(GL_LIGHT®) ; 


// Enable color tracking 
glEnable(GL_COLOR_MATERIAL) ; 


// Set material properties to follow glColor values 
glColorMaterial(GL_FRONT, GL_AMBIENT_AND DIFFUSE) ; 


// All materials hereafter have full specular reflectivity 
// with a high shine 

glMaterialfv(GL_FRONT, GL_SPECULAR, specref) ; 
glMateriali(GL_FRONT, GL_SHININESS, 128) ; 


// Black background 
glClearColor(0.0f, @.0f, 0.0f, 1.0f ); 
} 


The following line from the listing is actually what makes a positional light source into a 
spotlight: 


// Specific spot effects 
// Cut off angle is 60 degrees 
glLightf(GL_LIGHTO,GL_SPOT_CUTOFF,60.0f) ; 


The GL_SPOT_CUTOFF value specifies the radial angle of the cone of light emanating from 
the spotlight, from the center line to the edge of the cone. For a normal positional light, 
this value is 180° so that the light is not confined to a cone. In fact, for spotlights, only 
values from 0 to 90° are valid. Spotlights emit a cone of light, and objects outside this 
cone are not illuminated. Figure 5.32 shows how this angle translates to the cone width. 
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FIGURE 5.32 The angle of the spotlight cone. 


Drawing a Spotlight 

When you place a spotlight in a scene, the light must come from somewhere. Just because 
you have a source of light at some location doesn’t mean that you see a bright spot there. 
For our SPOT sample program, we placed a red cone at the spotlight source to show where 
the light was coming from. Inside the end of this cone, we placed a bright yellow sphere 
to simulate a light bulb. 


This sample has a pop-up menu that we use to demonstrate several things. The pop-up 
menu contains items to set flat and smooth shading and to produce a sphere for low, 
medium, and high tessellation. Tessellation means to break a mesh of polygons into a finer 
mesh of polygons (more vertices). Figure 5.33 shows a wireframe representation of a 
highly tessellated sphere next to one that has few polygons. 


FIGURE 5.33 On the left is a highly tessellated sphere; on the right, a sphere made up of few 
polygons. 


Figure 5.34 shows our sample in its initial state with the spotlight moved off slightly to 
one side. (You can use the arrow keys to move the spotlight.) The sphere consists of few 
polygons, which are flat shaded. In Windows, use the right mouse button to open a pop- 
up menu (Ctrl-click on the Mac), where you can switch between smooth and flat shading 
and between very low, medium, and very high tessellation for the sphere. Listing 5.7 
shows the complete code to render the scene. 
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Spot Light 


FIGURE 5.34 The SPOT sample—low tessellation, flat shading. 


LISTING 5.7 The Rendering Function for SPOT, Showing How the Spotlight Is Moved 


// Called to draw scene 
void RenderScene(void) 
{ 
if(iShade == MODE_FLAT) 
glShadeModel(GL_FLAT) ; 
else // iShade = MODE_SMOOTH; 
glShadeMode1l(GL_SMOOTH) ; 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 


// First place the light 

// Save the coordinate transformation 

glPushMatrix(); 
// Rotate coordinate system 
glRotatef(yRot, @.0f, 1.0f, 0.0f); 
glRotatef(xRot, 1.0f, 0.0f, 0.0f); 


// Specify new position and direction in rotated coords 
glLightfv(GL_LIGHTO,GL_POSITION, lightPos) ; 
glLightfv(GL_LIGHTO,GL_SPOT_DIRECTION, spotDir) ; 


// Draw a red cone to enclose the light source 
glColor3ub(255,0,0) ; 
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LISTING 5.7 Continued 


// Translate origin to move the cone out to where the light 
// is positioned. 

glTranslatef (lightPos[] ,lightPos[1],lightPos[2]); 
glutSolidCone(4.0f,6.0f, 15,15); 


// Draw a smaller displaced sphere to denote the light bulb 
// Save the lighting state variables 
glPushAttrib(GL_LIGHTING BIT) ; 


// Turn off lighting and specify a bright yellow sphere 
glDisable(GL_LIGHTING) ; 

glColor3ub(255,255,0); 
glutSolidSphere(3.0f, 15, 15); 


// Restore lighting state variables 
glPopAttrib(); 


// Restore coordinate transformations 
glPopMatrix(); 


// Set material color and draw a sphere in the middle 
glColor3ub(@, @, 255); 


if(iTess == MODE_VERYLOW) 
glutSolidSphere(30.0f, 7, 7); 
else 
if(iTess == MODE_MEDIUM) 
glutSolidSphere(30.0f, 15, 15); 
else // iTess = MODE_MEDIUM; 
glutSolidSphere(30.0f, 50, 50); 


// Display the results 
glutSwapBuffers(); 
} 


The variables iTess and iMode are set by the GLUT menu handler and control how many 
sections the sphere is broken into and whether flat or smooth shading is employed. Note 
that the light is positioned before any geometry is rendered. As pointed out in Chapter 2, 
OpenGL is an immediate-mode API: If you want an object to be illuminated, you have to 
put the light where you want it before drawing the object. 


255 


256 CHAPTER 5 Color, Materials, and Lighting: The Basics 


You can see in Figure 5.34 that the sphere is coarsely lit and each flat face is clearly 
evident. Switching to smooth shading helps a little, as shown in Figure 5.35. 


7 Spot Light 


FIGURE 5.35 Smoothly shaded but inadequate tessellation. 


Increasing the tessellation helps, as shown in Figure 5.36, but you still see disturbing arti- 
facts as you move the spotlight around the sphere. These lighting artifacts are one of the 
drawbacks of OpenGL lighting. A better way to characterize this situation is that these arti- 
facts are a drawback of vertex lighting (not necessarily OpenGL!). By lighting the vertices 
and then interpolating between them, we get a crude approximation of lighting. This 
approach is sufficient for many cases, but as you can see in our spot example, it is not 
sufficient in others. If you switch to very high tessellation and move the spotlight, you see 
the lighting blemishes all but vanish. 


As OpenGL hardware accelerators begin to accelerate transformations and lighting effects, 
and as CPUs become more powerful, you will be able to more finely tessellate your geome- 
try for better OpenGL-based lighting effects. 


The final observation you need to make about the SPOT sample appears when you set the 
sphere for medium tessellation and flat shading. As shown in Figure 5.37, each face of 
the sphere is flatly lit. Each vertex is the same color but is modulated by the value of the 
normal and the light. With flat shading, each polygon is made the color of the last vertex 
color specified and not smoothly interpolated between each one. 
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FIGURE 5.36 Choosing a finer mesh of polygons yields better vertex lighting. nn 


: Spot Light 


FIGURE 5.37 A multifaceted sphere. 
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Shadows 


A chapter on color and lighting naturally calls for a discussion of shadows. Adding 
shadows to your scenes can greatly improve their realism and visual effectiveness. In 
Figures 5.38 and 5.39, you see two views of a lighted cube. Although both are lit, the one 
with a shadow is more convincing than the one without the shadow. 


FIGURE 5.38 Lighted cube without a shadow. 


FIGURE 5.39 Lighted cube with a shadow. 


What Is a Shadow? 


Conceptually, drawing a shadow is quite simple. A shadow is produced when an object 
keeps light from a light source from striking some object or surface behind the object 
casting the shadow. The area on the shadowed object’s surface, outlined by the 

object casting the shadow, appears dark. We can produce a shadow programmatically by 
flattening the original object into the plane of the surface in which the object lies. The 
object is then drawn in black or some dark color, perhaps with some translucence. There 
are many methods and algorithms for drawing shadows, some quite complex. This book’s 
primary focus is on the OpenGL API. It is our hope that, after you’ve mastered the tool, 


Shadows 


some of the additional reading suggested in Appendix A will provide you with a lifetime 
of learning new applications for this tool. Chapter 18, “Depth Textures and Shadows,” 
covers some new direct support in OpenGL for making shadows; for our purposes in this 
chapter, we demonstrate one of the simpler methods that works quite well when casting 
shadows on a flat surface (such as the ground). Figure 5.40 illustrates this flattening. 


FIGURE 5.40 Flattening an object to create a shadow. 


We squish an object against another surface by using some of the advanced matrix manip- 
ulations we touched on in the preceding chapter. Here, we boil down this process to make 
it as simple as possible. 


Squish Code 

We need to flatten the modelview projection matrix so that any and all objects drawn into 
it are now in this flattened two-dimensional world. No matter how the object is oriented, 
it is squished into the plane in which the shadow lies. The next two considerations are the 
distance and direction of the light source. The direction of the light source determines the 
shape of the shadow and influences the size. If you’ve ever seen your shadow in the early 
or late morning hours, you know how long and warped your shadow can appear depend- 
ing on the position of the sun. 


The function gltMakeShadowMatrix from the glTools library, shown in Listing 5.8, takes 
three points that lie in the plane in which you want the shadow to appear (these three 
points cannot be along the same straight line!), the position of the light source, and 
finally a pointer to a transformation matrix that this function constructs. We won’t delve 
too much into linear algebra, but you do need to know that this function deduces the 
coefficients of the equation of the plane in which the shadow appears and uses it along 
with the lighting position to build a transformation matrix. If you multiply this matrix by 
the current modelview matrix, all further drawing is flattened into this plane. 
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LISTING 5.8 Function to Make a Shadow Transformation Matrix 


// Creates a shadow projection matrix out of the plane equation 

// coefficients and the position of the light. The return value is stored 

// in destMat 

void gltMakeShadowMatrix(GLTVector3 vPoints[3], GLTVector4 vLightPos, 
GLTMatrix destMat) 


4 
GLTVector4 vPlaneEquation; 
GLfloat dot; 


gltGetPlaneEquation(vPoints[®], vPoints[1], vPoints[2], vPlaneEquation) ; 


// Dot product of plane and light position 

dot = vPlaneEquation[®]*vLightPos[0] + 
vPlaneEquation[1]*vLightPos[1] + 
vPlaneEquation[2]*vLightPos[2] + 
vPlaneEquation[3]*vLightPos[3] ; 


// Now do the projection 

// First column 

destMat[@] = dot - vLightPos[0] * vPlaneEquation[0]; 
destMat[4] @.0f - vLightPos[@] * vPlaneEquation[1]; 
destMat[8] @.0f - vLightPos[0] * vPlaneEquation[2]; 
destMat[12] = @.0f - vLightPos[®] * vPlaneEquation[3]; 


// Second column 

destMat[1] = 0.0f - vLightPos[1] * vPlaneEquation[0]; 
destMat[5] = dot - vLightPos[1] * vPlaneEquation[1]; 
destMat[9] = 0.0f - vLightPos[1] * vPlaneEquation[2]; 
destMat[13] = 0.0f - vLightPos[1] * vPlaneEquation[3]; 


// Third Column 

destMat[2] = @.0f - vLightPos[2] * vPlaneEquation[®]; 
destMat[6] = 0.0f - vLightPos[2] * vPlaneEquation[1]; 
destMat[10] = dot - vLightPos[2] * vPlaneEquation[2]; 
destMat[14] = 0.0f - vLightPos[2] * vPlaneEquation[3]; 


// Fourth Column 

destMat[3] = 0.0f - vLightPos[3] * vPlaneEquation[Q]; 
destMat[7] = @.0f - vLightPos[3] * vPlaneEquation[1]; 
destMat[11] = 0.0f - vLightPos[3] * vPlaneEquation[2]; 
destMat[15] = dot - vLightPos[3] * vPlaneEquation[3] ; 
} 


nc TT EEE! 
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A Shadow Example 

To demonstrate the use of the function in Listing 5.8, we suspend our jet in air high above 
the ground. We place the light source directly above and a bit to the left of the jet. As you 
use the arrow keys to spin the jet around, the shadow cast by the jet appears flattened on 
the ground below. The output from this SHADOW sample program is shown in Figure 
5.41. 


: Shadow 


FIGURE 5.41 Output from the SHADOW sample program. 


The code in Listing 5.9 shows how the shadow projection matrix was created for this 
example. Note that we create the matrix once in SetupRC and save it in a global variable. 


LISTING 5.9 Setting Up the Shadow Projection Matrix 
GLfloat lightPos[] = { -75.0f, 150.0f, -50.0f, 0.0f }; 


// Transformation matrix to project shadow 
GLTMatrix shadowMat; 


// This function does any needed initialization on the rendering 
// context. Here it sets up and initializes the lighting for 
// the scene. 
void SetupRC() 
{ 
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LISTING 5.9 Continued 


// Any three points on the ground (counterclockwise order) 
GLTVector3 points[3] = {{ -30.0f, -149.0f, -20.0f }, 

{ -30.0f, -149.0f, 20.0f }, 

{ 40.0f, -149.0f, 20.0f }}; 


glEnable(GL_DEPTH_TEST) ; // Hidden surface removal 
glFrontFace(GL_CCW) ; // Counterclockwise polygons face out 
glEnable(GL_CULL_FACE) ; // Do not calculate inside of jet 


// Enable lighting 
glEnable(GL_LIGHTING) ; 


// Code to set up lighting, etc. 


// Light blue background 
glClearColor(0.0f, 0.0f, 1.0f, 1.0f ); 


// Calculate projection matrix to draw shadow on the ground 
gltMakeShadowMatrix(points, lightPos, shadowMat) ; 
} 


Listing 5.10 shows the rendering code for the shadow example. We first draw the ground. 
Then we draw the jet as we normally do, restore the modelview matrix, and multiply it by 
the shadow matrix. This procedure creates our squish matrix. Then we draw the jet again. 
(We’ve modified our code to accept a flag telling the DrawJet function to render in color 
or black.) After restoring the modelview matrix once again, we draw a small yellow sphere 
to approximate the position of the light. Note that we disable depth testing before we 
draw a plane below the jet to indicate the ground. 


This rectangle lies in the same plane in which our shadow is drawn, and we want to make 
sure the shadow is drawn. We have never before discussed what happens if we draw two 
objects or planes in the same location. We have discussed depth testing as a means to 
determine what is drawn in front of what, however. If two objects occupy the same loca- 
tion, usually the last one drawn is shown. Sometimes, however, an effect called z-fighting 
causes fragments from both objects to be intermingled, resulting in a mess! 
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LISTING 5.10 Rendering the Jet and Its Shadow 


// Called to draw scene 

void RenderScene (void) 
{ 
// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH BUFFER BIT); 


// Draw the ground; we do manual shading to a darker green 
// in the background to give the illusion of depth 
glBegin(GL_QUADS) ; 
glColor3ub(@,32,0); 
glVertex3f (400.0f, -150.0f, -200.0f); 
glVertex3f(-400.0f, -150.0f, -200.0f); 
glColor3ub(,255,0) ; 
glVertex3f(-400.0f, -150.0f, 200.0f); 
glVertex3f (400.0f, -150.0f, 200.0f); 
glEnd(); 


// Save the matrix state and do the rotations 
glPushMatrix(); 


// Draw jet at new orientation; put light in correct position 
// before rotating the jet 

glEnable(GL_LIGHTING) ; 
glLightfv(GL_LIGHT®,GL_POSITION, lightPos) ; 

glRotatef(xRot, 1.0f, 0.0f, 0.Of); 

glRotatef(yRot, 0.0f, 1.0f, 0.0f); 


DrawJet (FALSE) ; 


// Restore original matrix state 
glPopMatrix(); 


// Get ready to draw the shadow and the ground 

// First disable lighting and save the projection state 
glDisable(GL_DEPTH_TEST) ; 

glDisable(GL_LIGHTING) ; 

glPushMatrix(); 


// Multiply by shadow projection matrix 
glMultMatrixf((GLfloat *)shadowMat) ; 
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LISTING 5.10 Continued 


// Now rotate the jet around in the new flattened space 
glRotatef(xRot, 1.0f, 0.0f, 0.0f); 
glRotatef(yRot, 0.0f, 1.0f, 0.0f); 


// Pass true to indicate drawing shadow 
DrawJet (TRUE) ; 


// Restore the projection to normal 
glPopMatrix() ; 


// Draw the light source 

glPushMatrix(); 
glTranslatef(lightPos[@],lightPos[1], lightPos[2]); 
glColor3ub(255,255,0) ; 

glutSolidSphere(5.0f ,10,10); 

glPopMatrix(); 


// Restore lighting state variables 
glEnable(GL_DEPTH_TEST) ; 


// Display the results 
glutSwapBuffers(); 
} 


Sphere World Revisited 


Our last example for this chapter is too long to list the source code in its entirety. In the 
preceding chapter’s SPHEREWORLD sample program, we created an immersive 3D world 
with animation and camera movement. In this chapter, we revisit Sphere World and have 
added lights and material properties to the torus and sphere inhabitants. Finally, we have 
also used our planar shadow technique to add a shadow to the ground! We will keep 
coming back to this example from time to time as we add more and more of our OpenGL 
functionality to the code. The output of this chapter’s version of SPHEREWORLD is shown 
in Figure 5.42. 
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FIGURE 5.42 _ Fully lit and shadowed Sphere World. 


Summary 


This chapter introduced some of the more magical and powerful capabilities of OpenGL. 
We started by adding color to 3D scenes and smooth shading. We then saw how to specify 
one or more light sources and define their lighting characteristics in terms of ambient, 
diffuse, and specular components. We explained how the corresponding material proper- 
ties interact with these light sources and demonstrated some special effects, such as adding 
specular highlights and softening sharp edges between adjoining triangles. 


Also covered were lighting positions and the creation and manipulation of spotlights. The 
high-level matrix munching function presented here makes shadow generation as easy as 
it gets for planar shadows. 
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Reference 


glColor 


Purpose: Sets the current color when in RGBA color mode. 


Include File: <gl.h> 


Variations: 


void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 


glColor3b(GLbyte red, GLbyte green, GLbyte blue); 
glColor3d(GLdouble red, GLdouble green, GLdouble blue); 
glColor3f(GLfloat red, GLfloat green, GLfloat blue); 
glColor3i(GLint red, GLint green, GLint blue); 

glColor3s(GLshort red, GLshort green, GLshort blue); 
glColor3ub(GLubyte red, GLubyte green, GLubyte blue); 
glColor3ui(GLuint red, GLuint green, GLuint blue); 
glColor3us(GLushort red, GLushort green, GLushort blue) ; 
glColor4b(GLbyte red, GLbyte green, GLbyte blue, GLbyte alpha); 
glColor4d(GLdouble red, GLdouble green, GLdouble blue, GLdouble alpha); 
glColor4f(GLfloat red, GLfloat green, GLfloat blue, GLfloat alpha); 
glColor4i(GLint red, GLint green, GLint blue, GLint alpha); 
glColor4s(GLshort red, GLshort green, GLshort blue, GLshort alpha); 
glColor4ub(GLubyte red, GLubyte green, GLubyte blue, GLubyte alpha); 
glColor4ui(GLuint red, GLuint green, GLuint blue, GLuint alpha); 
glColor4us(GLushort red, GLushort green, GLushort blue, GLushort alpha); 
glColor3bv(const GLbyte *v); 

glColor3dv(const GLdouble *v); 

glColor3fv(const GLfloat *v); 

glColor3iv(const GLint *v); 

glColor8sv(const GLshort *v); 

glColor3ubv(const GLubyte *v); 

glColor8uiv(const GLuint *v); 

glColor3usv(const GLushort *v); 

glColor4bv(const GLbyte *v); 

glColor4dv(const GLdouble *v); 

glColor4fv(const GLfloat *v); 

glColor4iv(const GLint *v); 

glColor4sv(const GLshort *v); 

glColor4ubv(const GLubyte *v); 

glColor4uiv(const GLuint *v); 

glColor4usv(const GLushort *v); 


Description: 


Parameters: 
red 

green 

blue 

alpha 


*y 
Returns: 
See Also: 


glColorMask 


Purpose: 


Include File: 
Syntax: 


Reference 


This function sets the current color by specifying separate red, green, and 
blue components of the color. Some functions also accept an alpha 
component. Each component represents the range of intensity from zero 
(0.0) to full intensity (1.0). Functions with the v suffix take a pointer to 
an array that specifies the components. Each element in the array must 
be the same type. When the alpha component is not specified, it is 
implicitly set to 1.0. When non-floating-point types are specified, the 
range from zero to the largest value represented by that type is mapped 
to the floating-point range 0.0 to 1.0. 


Specifies the red component of the color. 
Specifies the green component of the color. 
Specifies the blue component of the color. 


Specifies the alpha component of the color. Used only in variations that 
take four arguments. 


A pointer to an array of red, green, blue, and possibly alpha values. 
None. 
glColorMaterial, glMaterial 


Enables or disables modification of color components in the color 
buffers. 


<gl.h> 


void glColorMask(GLboolean bRed, GLboolean bGreen, GLboolean bBlue, 
GLboolean bAlpha); 


Description: 


Parameters: 
bRed 
bGreen 
bBlue 
bAlpha 
Returns: 
See Also: 


This function allows changes to individual color components in the color 
buffer to be disabled or enabled. (All are enabled by default.) For 
example, setting the bAlpha argument to GL_FALSE disallows changes to 
the alpha color components. 


GLboolean: Specifies whether the red component can be modified. 
GLboolean: Specifies whether the green component can be modified. 
GLboolean: Specifies whether the blue component can be modified. 
GLboolean: Specifies whether the alpha component can be modified. 
None. 

glColor 
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glColorMaterial 


Purpose: Allows material colors to track the current color as set by glColor. 
Include File: <gl.h> 

Syntax: 

void glColorMaterial(GLenum face, GLenum mode) ; 


Description: This function allows material properties to be set without having to call 
glMaterial directly. By using this function, you can set certain material 
properties to follow the current color as specified by g1Color. By default, 
color tracking is disabled; to enable it, you must also call 
glEnable(GL_COLOR_MATERIAL). To disable color tracking again, you call 
glDisable(GL_COLOR_MATERIAL). 


Parameters: 

face GLenum: Specifies whether the front (GL_FRONT), back (GL_BACK), or both 
(GL_FRONT_AND_BACK) should follow the current color. 

mode GLenum: Specifies which material property should be following the current 
color. This can be GL_EMISSION, GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, or 
GL_AMBIENT_AND_DIFFUSE. 

Returns: None. 

See Also: glColor, glMaterial, glLight, glLightModel 

glGetLight 

Purpose: Returns information about the current light source settings. 

Include File: <gl.h> 

Variations: 


void glGetLightfv(GLenum light, GLenum pname, GLfloat *params) ; 
void glGetLightiv(GLenum light, GLenum pname, GLint *params) ; 


Description: You use this function to query the current settings for one of the eight 
supported light sources. The return values are stored at the address 
pointed to by params. For most properties, this is an array of four values 
containing the RGBA components of the properties specified. 

Parameters: 


light GLenum: Specifies the light source for which information is being 
requested. This ranges from 0 to GL_MAX_LIGHTS (a minimum of 8 is 
required by specification). Constant light values are enumerated from 
GL_LIGHT® to GL_LIGHT7. 


Reference 


pname GLenum: Specifies which property of the light source is being queried. Any 
of the following values are valid: GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, 
GL_POSITION, GL_SPOT_DIRECTION, GL_SPOT_EXPONENT, GL_SPOT_CUTOFF, 
GL_CONSTANT_ATTENUATION, GL_LINEAR_ATTENUATION, and 
GL_QUADRATIC_ATTENUATION. 


params GLfloat* or GLint*: Specifies an array of integer or floating-point values 
representing the return values. These return values are in the form of an 
array of four or three or a single value. Table 5.2 shows the return value 
meanings for each property. 


TABLE 5.2 Valid Lighting Parameters for glGetLight 


Property Meaning of Return Values 

GL_AMBIENT Four RGBA components. 

GL_DIFFUSE Four RGBA components. 

GL_SPECULAR Four RGBA components. 

GL_POSITION Four elements that specify the position of the light source. The first 


three elements specify the position of the light. The fourth, if 1.0, 
specifies that the light is at this position. Otherwise, the light source 
is directional and all rays are parallel. 


GL_SPOT_DIRECTION Three elements specifying the direction of the spotlight. This vector is 
not normalized and is in eye coordinates. 
GL_SPOT_EXPONENT A single value representing the spot exponent. 
GL_SPOT_CUTOFF A single value representing the cutoff angle of the spot source. 
GL_CONSTANT_ATTENUATION A single value representing the constant attenuation of the light. 
GL_LINEAR_ATTENUATION A single value representing the linear attenuation of the light. 
GL_QUADRATIC_ATTENUATION A single value representing the quadratic attenuation of the light. 
Returns: None. 
See Also: glLight 
glGetMaterial 
Purpose: Returns the current material property settings. 


Include File: <gl.h> 
Variations: 


void glGetMaterialfv(GLenum face, GLenum pname, GLfloat *params) ; 
void glGetMaterialiv(GLenum face, GLenum pname, GLint *params); 


Description: You use this function to query the current front or back material proper- 
ties. The return values are stored at the address pointed to by params. For 
most properties, this is an array of four values containing the RGBA 
components of the property specified. 
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Parameters: 

face GLenum: Specifies whether the front (GL_FRONT) or back (GL_BACK) material 
properties are being sought. 

pname GLenum: Specifies which material property is being queried. Valid values 


are GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, GL_EMISSION, GL_SHININESS, 
and. GL_COLOR_INDEXES. 


params GLint* or GLfloat*: Specifies an array of integer or floating-point values 
representing the return values. For GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, 
and GL_EMISSION, this is a four-element array containing the RGBA values 
of the property specified. For GL_SHININESS, a single value representing 
the specular exponent of the material is returned. GL_COLOR_INDEXES 
returns an array of three elements containing the ambient, diffuse, and 
specular components in the form of color indexes. GL_COLOR_INDEXES is 
used only for color index lighting. 


Returns: None. 

See Also: glMaterial 

glLight 

Purpose: Sets light source parameters for one of the available light sources. 


Include File: <gl.h> 
Variations: 


void glLightf(GLenum light, GLenum pname, GLfloat param); 

void glLighti(GLenum light, GLenum pname, GLint param) ; 

void glLightfv(GLenum light, GLenum pname, const GLfloat*params) ; 
void glLightiv(GLenum light, GLenum pname, const GLint *params) ; 


Description: You use this function to set the lighting parameters for one of the eight 
supported light sources. The first two variations of this function require 
only a single parameter value to set one of the following properties: 
GL_SPOT_EXPONENT, GL_SPOT_CUTOFF, GL_CONSTANT_ATTENUATION, 
GL_LINEAR_ATTENUATION, and GL_QUADRATIC_ATTENUATION. The second 
two variations are used for lighting parameters that require an array of 
multiple values. They include GL_AMBIENT, GL_DIFFUSE, GL_SPECULAR, 
GL_POSITION, and GL_SPOT_DIRECTION. You can also use these variations 
with single-valued parameters by specifying a single element array for 
*params. 


Reference 


Parameters: 

light GLenum: Specifies which light source is being modified. This ranges from 0 
to GL_MAX_LIGHTS (8 minimum). Constant light values are enumerated 
from GL_LIGHT@ to GL_LIGHT7. 

pname GLenum: Specifies which lighting parameter is being set by this function 
call. See Table 5.2 for a complete list and the meaning of these parame- 
ters. 

param GLfloat or GLint: Specifies the value for parameters that are specified by 
a single value. These parameters are GL_SPOT_EXPONENT, GL_SPOT_CUTOFF, 
GL_CONSTANT_ATTENUATION, GL_LINEAR_ATTENUATION, and GL_QUADRATIC_ 
ATTENUATION. These parameters have meaning only for spotlights. 

params GLfloat* or GLint*: Specifies an array of values that fully describe the 
parameters being set. See Table 5.2 for a list and the meaning of these 
parameters. 

Returns: None. 

See Also: glGetLight 

glLightModel 

Purpose: Sets the lighting model parameters used by OpenGL. 


Include File: 
Variations: 


<gl.h> 


void glLightModelf(GLenum pname, GLfloat param) 

void glLightModeli(GLenum pname, GLint param); 

void glLightModelfv(GLenum pname, const GLfloat *params) ; 
void glLightModeliv(GLenum pname, const GLint *params) ; 


Description: 


You use this function to set the lighting model parameters used by 
OpenGL. You can set any or all of three lighting model parameters. 
GL_LIGHT_MODEL_AMBIENT is used to set the default ambient illumination 
for a scene. By default, this light has an RGBA value of (0.2, 0.2, 0.2, 1.0). 
Only the last two variations can be used to set this lighting model 
because they take pointers to an array that can contain the RGBA values. 


The GL_LIGHT_MODEL_TWO_SIDE parameter is specified to indicate whether 
both sides of polygons are illuminated. By default, only the front 
(defined by winding) of polygons is illuminated, using the front material 
properties as specified by glMaterial. Specifying a lighting model para- 
meter of GL_LIGHT_MODEL_LOCAL_ VIEWER modifies the calculation of 
specular reflection angles, whether the view is down along the negative z- 
axis or from the origin of the eye coordinate system. Finally, 
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Parameters: 


pname 


param 


params 


Returns: 
See Also: 


g!Material 
Purpose: 
Include File: 
Variations: 


GL_LIGHT_MODEL_COLOR control can be used to specify whether specular 
lighting produces a second color (textures get specular light) or whether 
all three lighting components are combined with GL_SINGLE_COLOR. 


GLenum: Specifies a lighting model parameter. GL_LIGHT_MODEL_AMBIENT, 
GL_LIGHT_MODEL_LOCAL_VIEWER, GL_LIGHT_MODEL_TWO_SIDE, and 
GL_LIGHT_MODEL_COLOR_CONTROL are accepted. 


GLfloat or GLint: For GL_LIGHT_MODEL_LOCAL_VIEWER, a value of 0.0 indi- 
cates that specular lighting angles take the view direction to be parallel to 
and in the direction of the negative z-axis. Any other value indicates that 
the view is from the origin of eye coordinate system. For 
GL_LIGHT_MODEL_TWO_SIDE, a value of 0.0 indicates that only the fronts of 
polygons are to be included in illumination calculations. Any other value 
indicates that both the front and back are included. This parameter has 
no effect on points, lines, or bitmaps. For 
GL_LIGHT_MODEL_COLOR_CONTROL, the valid values are GL_SEPARATE_ 
SPECULAR_COLOR or GL_SINGLE_COLOR. 


GLfloat* or GLint*: For GL_LIGHT_MODEL_AMBIENT or GL_LIGHT_MODEL_ 
LOCAL_VIEWER, this points to an array of integers or floating-point values, 
only the first element of which is used to set the parameter value. For 
GL_LIGHT_ MODEL_AMBIENT, this array points to four values that indicate 
the RGBA components of the ambient light. 


None. 
glLight, glMaterial 


Sets material parameters for use by the lighting model. 
<gl.h> 


void glMaterialf(GLenum face, GLenum pname, GLfloat param); 

void glMateriali(GLenum face, GLenum pname, GLint param); 

void glMaterialfv(GLenum face, GLenum pname, const GLfloat params) 
void glMaterialiv(GLenum face, GLenum pname, const GLint params) ; 


Description: 


You use this function to set the material reflectance properties of poly- 
gons. The GL_AMBIENT, GL_DIFFUSE, and GL_SPECULAR properties affect 
how these components of incident light are reflected. GL_EMISSION is 
used for materials that appear to give off their own light. G__SHININESS 
can vary from 0 to 128, with the higher values producing a larger specu- 
lar highlight on the material surface. You use GL_COLOR_INDEXES for mate- 
rial reflectance properties in color index mode. 


Parameters: 
face 


pname 


param 
params 


Returns: 
See Also: 


glNormal 
Purpose: 
Include File: 
Variations: 


Reference 


GLenum: Specifies whether the front, back, or both material properties of 
the polygons are being set by this function. May be either GL_FRONT, 
GL_BACK, or GL_FRONT_AND_BACK. 


GLenum: Specifies the single-valued material parameter being set for the 
first two variations. Currently, the only single-valued material parameter 
is GL_SHININESS. The second two variations, which take arrays for their 
parameters, can set the following material properties: GL_AMBIENT, 
GL_DIFFUSE, GL_SPECULAR, GL_EMISSION, GL_SHININESS, 
GL_AMBIENT_AND_DIFFUSE, or GL_COLOR_INDEXES. 

GLfloat or GLint: Specifies the value to which the parameter specified by 
pname (GL_SHININESS) is set. 

GLfloat* or GLint*: Specifies an array of floats or integers that contain 
the components of the property being set. 

None. 


glGetMaterial, glColorMaterial, glLight, glLightModel 


Defines a surface normal for the next vertex or set of vertices specified. 
<gl.h> 


void glNormal3b(GLbyte nx, GLbyte ny, GLbyte nz); 

void glNormal3d(GLdouble nx, GLdouble ny, GLdouble nz); 
void glNormal3f(GLfloat nx, GLfloat ny, GLfloat nz); 
void glNormal3i(GLint nx, GLint ny, GLint nz); 

void glNormal3s(GLshort nx, GLshort ny, GLshort nz); 
void glNormal3bv(const GLbyte *v); 

void glNormal3dv(const GLdouble *v); 

void glNormal3fv(const GLfloat *v); 

void glNormal3iv(const GLint *v); 

void glNormal3sv(const GLshort *v); 


Description: 


The normal vector specifies which direction is up and perpendicular to 
the surface of the polygon. This function is used for lighting and shading 
calculations. Specifying a unit vector of length 1 improves rendering 
speed. OpenGL automatically converts your normals to unit normals if 
you enable this with glEnable(GL_NORMALIZE) ;. 
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Parameters: 

nx Specifies the x magnitude of the normal vector. 

ny Specifies the y magnitude of the normal vector. 

nz Specifies the z magnitude of the normal vector. 

Vv Specifies an array of three elements containing the x, y, and z magnitudes 
of the normal vector. 

Returns: None. 

See Also: glTexCoord, glVertex 

glShadeModel 

Purpose: Sets the default shading to flat or smooth. 


Include File: 


Syntax: 


<gl.h> 


void glShadeModel(GLenum mode) ; 


Description: 


Parameters: 


mode 


Returns: 
See Also: 


OpenGL primitives are always shaded, but the shading model can be flat 
(GL_FLAT) or smooth (GL_SMOOTH). In the simplest of scenarios, one color 
is set with glColor before a primitive is drawn. This primitive is solid and 
flat (does not vary) throughout, regardless of the shading. If a different 
color is specified for each vertex, the resulting image varies with the 
shading model. With smooth shading, the color of the polygon’s interior 
points are interpolated from the colors specified at the vertices. This 
means the color varies from one color to the next between two vertices. 
The color variation follows a line through the color cube between the 
two colors. If lighting is enabled, OpenGL performs other calculations to 
determine the correct value for each vertex. In flat shading, the color 
specified for the last vertex is used throughout the region of the primi- 
tive. The only exception is for GL_POLYGON, in which case, the color used 
throughout the region is the one specified for the first vertex. 


GLenum: Specifies the shading model to use, either GL_FLAT or GL_SMOOTH. 
The default is GL_SMOOTH. 


None. 
glColor, glLight, glLightModel 


CHAPTER 6 


More on Colors and Materials 


by Richard S. Wright, Jr. 


WHAT YOU'LL LEARN IN THIS CHAPTER: 


How To Functions You'll Use 

Blend colors and objects together glBlendFunc, gl1BlendFuncSeparate, glBlendEquation, 
glBlendColor 

Use alpha testing to eliminate fragments glAlphaFunc 

Add depth cues with fog glFog 

Render motion-blurred animation glAccum 


In the preceding chapter, you learned that there is more to making a ball appear red than 
just setting the drawing color to red. Material properties and lighting parameters can go a 
long way toward adding realism to your graphics, but modeling the real world has a few 
other challenges that we will address in this chapter. For starters, many effects are accom- 
plished by means of blending colors together. Transparent objects such as stained glass 
windows or plastic bottles allow you to see through them, but the light from the objects 
behind them is blended with the color of the transparent object you are seeing through. 
This type of transparency is achieved in OpenGL by drawing the background objects first 
and then blending the foreground object in front with the colors that are already present 
in the color buffer. A good part of making this technique work requires that we now 
consider the fourth color component that until now we have been ignoring, alpha. 


Blending 


You have already learned that OpenGL rendering places color values in the color buffer 
under normal circumstances. You have also learned that depth values for each fragment 
are also placed in the depth buffer. When depth testing is turned off (disabled), new color 
values simply overwrite any other values already present in the color buffer. When depth 
testing is turned on (enabled), new color fragments replace an existing fragment only if 
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they are deemed closer to the near clipping plane than the values already there. This is, of 
course, under normal circumstances. These rules suddenly no longer apply the moment 
you turn on OpenGL blending: 


glEnable(GL_BLENDING) ; 


When blending is enabled, the incoming color is combined with the color value already 
present in the color buffer. How these colors are combined leads to a great many and 
varied special effects. 


Combining Colors 

First, we must introduce a more official terminology for the color values coming in and 
already in the color buffer. The color value already stored in the color buffer is called the 
destination color, and this color value contains the three individual red, green, and blue 
components, and optionally a stored alpha value as well. A color value that is coming in 
as a result of more rendering commands that may or may not interact with the destina- 
tion color is called the source color. The source color also contains either three or four 
color components (red, green, blue, and optionally alpha). 


How the source and destination colors are combined when blending is enabled is 
controlled by the blending equation. By default, the blending equation looks like this: 


C,=(C,*S) +(C,* D) 
Here, C, is the final computed color, C, is the source color, C, is the destination color, and 


S and D are the source and destination blending factors. These blending factors are set 
with the following function: 


glBlendFunc(GLenum S, GLenum D); 
As you can see, S and D are enumerants and not physical values that you specify directly. 
Table 6.1 lists the possible values for the blending function. The subscripts stand for 


source, destination, and color (for blend color, to be discussed shortly). R, G, B, and A 
stand for Red, Green, Blue, and Alpha, respectively. 


TABLE 6.1 OpenGL Blending Factors 


Function RGB Blend Factors Alpha Blend Factor 
GL_ZERO (0,0,0) 0 

GL_ONE (1,1,1) 1 

GL_SRC_COLOR (R,,G,,B.) A, 
GL_ONE_MINUS_SRC_COLOR (1,1,1) - (R,G,B) 1-A, 
GL_DST_COLOR (RyG.,B,) A, 
GL_ONE_MINUS_DST_COLOR (1,1,1) - (R,,G,,B,) 1-A, 


GL_SRC_ALPHA (A,A,A) A 


Blending 


Function RGB Blend Factors Alpha Blend Factor 
GL_ONE_MINUS_SRC_ALPHA (1,1,1) - (A,A,A) 1-A, 
GL_DST_ALPHA (A,A,A) A, 
GL_ONE_MINUS_DST_ALPHA (1,1,1) - (A,A,A,) 1-A, 
GL_CONSTANT_COLOR (RGB) A. 
GL_ONE_MINUS_CONSTANT_COLOR (1,1,1) - (R.,G_,B.) 1-A, 
GL_CONSTANT_ALPHA (AAA) A. 
GL_ONE_MINUS_CONSTANT_ALPHA (1,1,1) — (A, A_,A,) 1-A, 
GL_SRC_ALPHA_SATURATE (fEA* 1 


Rds lee ee Cee eee A 


Remember that colors are represented by floating-point numbers, so adding them, 
subtracting them, and even multiplying them are all perfectly valid operations. Table 6.1 
may seem a bit bewildering, so let’s look at a common blending function combination: 


glBlendFunc(GL_SRC_ALPHA, GL_ONE MINUS SRC_ALPHA); 


This function tells OpenGL to take the source (incoming) color and multiply the color 
(the RGB values) by the alpha value. Add this to the result of multiplying the destination 
color by one minus the alpha value from the source. Say, for example, that you have the 
color Red (1.0f, 0.0f, 0.0f, 0.0f) already in the color buffer. This is the destination color, or 
C,. If something is drawn over this with the color blue and an alpha of 0.5 (0.0f, 0.0f, 1.0f, 
0.5f), you would compute the final color as follows: 

C, = destination color = (1.0f, 0.0f, 0.0f, 0.0f) 

C, = source color = (0.0f, 0.0f, 1.0f, 0.5f) 

S = source alpha = 0.5 


D = one minus source alpha = 1.0 - 0.5 = 0.5 


Now, the equation 


C,=(C,*S)+(C,*D) 


evaluates to 


C, = (Blue * 0.5) + (Red * 0.5) 


The final color is a scaled combination of the original red value with the incoming blue 
value. The higher the incoming alpha value, the more of the incoming color that is added 
and the less of the original color is retained. 


This blending function is often used to achieve the effect of drawing a transparent object 
in front of some other opaque object. This technique does require, however, that you draw 
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the background object or objects first and then draw the transparent object blended over 
the top. The effect can be quite dramatic. For example, in the REFLECTION sample 
program, we will use transparency to achieve the illusion of a reflection in a mirrored 
surface. We begin with a rotating torus with a sphere revolving around it, similar to the 
view in the preceding chapter’s Sphere World example. Beneath the torus and sphere, we 
will place a reflective tiled floor. The output from this program is shown in Figure 6.1, and 
the drawing code is shown in Listing 6.1. 


FIGURE 6.1 Using blending to create a fake reflection effect. 


LISTING 6.1 Rendering Function for the REFLECTION Program 


TLTTTTTT TTT TTT TTT TTT 
// Called to draw scene 
void RenderScene(void) 
{ 
// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT {| GL_DEPTH_BUFFER_BIT); 


glPushMatrix(); 
// Move light under floor to light the "reflected" world 


Blending 


LISTING 6.1. Continued 
glLightfv(GL_LIGHT@, GL_POSITION, fLightPosMirror) ; 
glPushMatrix(); 
glFrontFace(GL_CW); // geometry is mirrored, 
// swap orientation 


glScalef(1.0f, -1.0f, 1.0f); 

Draworld(); 

glFrontFace(GL_CCW) ; 
glPopMatrix(); 


// Draw the ground transparently over the reflection 
glDisable(GL_LIGHTING) ; 

glEnable(GL_BLEND) ; 

glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) ; 
DrawGround() ; 

glDisable(GL_BLEND) ; 

glEnable(GL_LIGHTING) ; 


// Restore correct lighting and draw the world correctly 
glLightfv(GL_LIGHT@, GL_POSITION, fLightPos) ; 
Draworld(); 

glPopMatrix(); 


// Do the buffer Swap 
glutSwapBuffers(); 
} 


The basic algorithm for this effect is to draw the scene upside down first. We use one func- 
tion to draw the scene, DrawWorld(), but to draw it upside down, we scale by -1 to invert 
the y-axis, reverse our polygon winding, and place the light down beneath us. After 
drawing the upside-down world, we draw the ground, but we use blending to create a 
transparent floor over the top of the inverted world. Finally, we turn off blending, put the 
light back overhead, and draw the world right side up. 


Changing the Blending Equation 
The blending equation we showed you earlier 


C,=(C,* $)+(C,*D) 
is the default blending equation. You can actually choose from five different blending 
equations, each given in Table 6.2 and selected with the following function: 


void glBlendEquation(GLenum mode) ; 
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TABLE 6.2 Available Blend Equation Modes 


Mode Function 
GL_FUNC_ADD (default) C, = (C, * S) + (C, * D) 
GL_FUNC_SUBTRACT C, = (C, * S)-(C, * D) 
GL_FUNC_REVERSE_SUBTRACT €,=(€5*D)=(C,*'S) 
GL_MIN C, = min(C, C,) 
GL_MAX C, = max(C, C ) 


In addition to g1BlendFunc, you have even more flexibility with this function: 


void glBlendFuncSeparate(GLenum srcRGB, GLenum dstRGB, GLenum srcAlpha, 
GLenum dstAlpha) ; 


Whereas g1BlendFunc specifies the blend functions for source and destination RGBA 
values, g1BlendFuncSeparate allows you to specify blending functions for the RGB and 
alpha components separately. 


Finally, as shown in Table 6.1, the GL_CONSTANT_COLOR, GL_ONE_MINUS_CONSTANT_COLOR, 
GL_CONSTANT_ALPHA, and GL_ONE_MINUS_CONSTANT_ALPHA values all allow a constant blend- 
ing color to be introduced to the blending equation. This constant blending color is 
initially black (0.0f, 0.0f, 0.0f, 0.0f), but can be changed with this function: 


void glBlendColor(GLclampf red, GLclampf green, Glclampf blue, GLclampf alpha); 


Antialiasing 

Another use for OpenGL’s blending capabilities is antialiasing. Under most circumstances, 
individual rendered fragments are mapped to individual pixels on a computer screen. 
These pixels are square (or squarish), and usually you can spot the division between two 
colors quite clearly. These jaggies, as they are often called, catch the eye’s attention and 
can destroy the illusion that the image is natural. These jaggies are a dead give-away that a 
computer-generated image is computer generated! For many rendering tasks, it is desirable 
to achieve as much realism as possible, particularly in games, simulations, or artistic 
endeavors. Figure 6.2 shows the output for the sample program SMOOTHER. In Figure 6.3, 
we have zoomed in on a line segment and some points to show the jagged edges. 


To get rid of the jagged edges between primitives, OpenGL uses blending to blend the 
color of the fragment with the destination color of the pixel and its surrounding pixels. In 
essence, pixel colors are smeared slightly to neighboring pixels along the edges of any 
primitives. 


Turning on antialiasing is simple. First, you must enable blending and set the blending 
function to be the same as you used in the preceding section for transparency: 


glEnable(GL_BLEND) ; 
glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) ; 
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—JSmoothing Out The Jaggies 


FIGURE 6.2 Output from the program SMOOTHER. 


FIGURE 6.3 A closer look at some jaggies. 
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You also need to make sure the blend equation is set to GL_ADD, but because this is the 
default and most common blending equation, we don’t show it here (changing the blend- 
ing equation is also not supported on all OpenGL implementations). After blending is 
enabled and the proper blending function and equation are selected, you can choose to 
antialias points, lines, and/or polygons (any solid primitive) by calling glEnable: 


glEnable(GL_POINT_SMOOTH) ; // Smooth out points 
glEnable(GL_LINE_SMOOTH) ; // Smooth out lines 
glEnable(GL_POLYGON_SMOOTH); // Smooth out polygon edges 


You should note, however, that GL_POLYGON_SMOOTH is not supported on all OpenGL imple- 
mentations. Listing 6.2 shows the code from the SMOOTHER program that responds to a 
pop-up menu that allows the user to switch between antialiased and non-antialiased 
rendering modes. When this program is run with antialiasing enabled, the points and 
lines appear smoother (fuzzier). In Figure 6.4, a zoomed-in section shows the same area as 
Figure 6.3, but now with the jagged edges somewhat reduced. 


FIGURE 6.4 No more jaggies! 


LISTING 6.2 Switching Between Antialiased and Normal Rendering 
FTTTATTTA TTT TTA TTT AAT ATA 


// Reset flags as appropriate in response to menu selections 
void ProcessMenu(int value) 


{ 


switch(value) 


Blending 


LISTING 6.2. Continued 


{ 


case 1: 


// Turn on antialiasing, and give hint to do the best 
// job possible. 

glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) ; 
glEnable(GL_BLEND) ; 

glEnable(GL_POINT_SMOOTH) ; 

glHint (GL_POINT_SMOOTH_HINT, GL_NICEST) ; 
glEnable(GL_LINE_SMOOTH) ; 
glHint(GL_LINE_SMOOTH_HINT, GL_NICEST) ; 
glEnable(GL_POLYGON_SMOOTH) ; 
glHint(GL_POLYGON_SMOOTH_HINT, GL_NICEST); 

break; 


case 2: 


// Turn off blending and all smoothing 
glDisable(GL_BLEND) ; 
glDisable(GL_LINE_SMOOTH) ; 
glDisable(GL_POINT_SMOOTH) ; 
glDisable(GL_POLYGON_SMOOTH) ; 

break; 


default: 


break; 


// Trigger a redraw 
glutPostRedisplay(); 


} 


Note especially here the calls to the glHint function that was discussed in Chapter 2, 
“Using OpenGL.” There are many algorithms and approaches to achieve antialiased primi- 
tives. Any specific OpenGL implementation may choose any one of those approaches, and 
perhaps even support two! You can ask OpenGL if it does support multiple antialiasing 
algorithms to choose one that is very fast (GL_FASTEST) or the one with the most accuracy 
in appearance (GL_NICEST). 


Multisample 

One of the biggest advantages to antialiasing is that it smoothes out the edges of primi- 
tives and can lend a more natural and realistic appearance to renderings. Point and line 
smoothing is widely supported, but unfortunately polygon smoothing is not available on 
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all platforms. Even when GL_POLYGON_SMOOTH is available, it is not as convenient a means 
of having your whole scene antialiased as you might think. Because it is based on the 
blending operation, you would need to sort all your primitives from front to back! Yuck. 


A more recent addition to OpenGL to address this shortcoming is multisampling. When 
this feature is supported (it is an OpenGL 1.3 feature), an additional buffer is added to the 
framebuffer that includes the color, depth, and stencil values. All primitives are sampled 
multiple times per pixel, and the results are stored in this buffer. These samples are 
resolved to a single value each time the pixel is updated, so from the programmer's stand- 
point, it appears automatic and happens “behind the scenes.” Naturally, this extra 
memory and processing that must take place are not without their performance penalties, 
and some implementations may not support multisampling for multiple rendering 
contexts. 


To get multisampling, you must first obtain a rendering context that has support for a 
multisampled framebuffer. This varies from platform to platform, but GLUT exposes a bit 
field (GLUT_MULTISAMPLE) that allows you to request this until you reach the operating 
system-specific chapters later. For example, to request a multisampled, full-color, double- 
buffered frame buffer with depth, you would call 


glutInitDisplayMode(GLUT_DOUBLE } GLUT_RGB | GLUT_DEPTH | GLUT_MULTISAMPLE); 


You can turn multisampling on and off using the glEnable/g1Disable combination and 
the GL_MULTISAMPLE token: 


glEnable(GL_MULTISAMPLE) ; 


or 


glDisable(GL_MULTISAMPLE) ; 


The sample program MULTISAMPLE is simply the Sphere World sample from the preced- 
ing chapter with multisampling selected and enabled. Figure 6.5 shows the difference 
between two zoomed-in sections from each program. You can see that multisampling 
really helps smooth out the geometry’s edges on the image to the right, lending to a much 
more pleasing appearance to the rendered output. 


Another important note about multisampling is that when it is enabled, the point, line, 
and polygon smoothing features are ignored if enabled. This means you cannot use point 
and line smoothing at the same time as multisampling. On a given OpenGL implementa- 
tion, points and lines may look better with smoothing turned on instead of multisam- 
pling. To accommodate this, you might turn off multisampling before drawing points and 
lines and then turn on multisampling for other solid geometry. The following pseudocode 
shows a rough outline of how to do this: 


glDisable(GL_MULTISAMPLE) ; 
glEnable(GL_POINT_SMOOTH) ; 


Blending 


// Draw some smooth points 
[Terese 
glDisable(GL_POINT_SMOOTH) ; 
glEnable(GL_MULTISAMPLE) ; 


FIGURE 6.5 Zoomed-in view contrasting normal and multisampled rendering. 


STATE SORTING 


Turning different OpenGL features on and off changes the internal state of the driver. These state 
changes can be costly in terms of rendering performance. Frequently, performance-sensitive 
programmers will go to great lengths to sort all the drawing commands so that geometry 
needing the same state will be drawn together. This state sorting is one of the more common 
techniques to improve rendering speed in games. 


The multisample buffers use the RGB values of fragments by default and do not include 
the alpha component of the colors. You can change this by calling glEnable with one of 
the following three values: 


® GL_SAMPLE_ALPHA_TO_COVERAGE—Use the alpha value. 
* GL_SAMPLE_ALPHA_TO_ONE—Set alpha to 1 and use it. 


© GL_SAMPLE_COVERAGE—Use the value set with glSampleCoverage. 


When GL_SAMPLE_COVERAGE is enabled, the g1SampleCoverage function allows you to 
specify a specific value that is ANDed (bitwise) with the fragment coverage value: 


void glSampleCoverage(GLclampf value, GLboolean invert) ; 


This fine-tuning of how the multisample operation works is not strictly specified by the 
specification, and the exact results may vary from implementation to implementation. 
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Fog 


Another easy-to-use special effect that OpenGL supports is fog. With fog, OpenGL blends a 
fog color that you specify with geometry after all other color computations have been 
completed. The amount of the fog color mixed with the geometry varies with the distance 
of the geometry from the camera origin. The result is a 3D scene that appears to contain 
fog. Fog can be useful for slowly obscuring objects as they “disappear” into the back- 
ground fog, or a slight amount of fog will produce a hazy effect on distant objects, provid- 
ing a powerful and realistic depth cue. Figure 6.6 shows output from the sample program 
FOGGED. As you can see, this is nothing more than the ubiquitous Sphere World example 
with fog turned on. 


FIGURE 6.6 Sphere World with fog. 


Listing 6.3 shows the few lines of code added to the SetupRC function to produce this 
effect. 


LISTING 6.3 Setting Up Fog for Our Sphere World 
// Grayish background 
glClearColor(fLowLight[®], flowLight[1], flowLight[2], flLowLight[3]); 


Fog 


LISTING 6.3 Continued 
// Setup Fog parameters 


glEnable(GL_FOG) ; // Turn Fog on 

glFogfv(GL_FOG_COLOR, flowLight); // Set fog color to match background 
glFogf(GL_FOG_START, 5.0f); // How far away does the fog start 
glFogf(GL_FOG_END, 30.0f); // How far away does the fog stop 


glFogi(GL_FOG_MODE, GL_LINEAR) ; // Which fog equation do I use? 


Turning fog on and off is as easy as using the following functions: 


glEnable/glDisable(GL_FOG) ; 


The means of changing fog parameters (how the fog behaves) is to use the glFog func- 
tion. There are several variations on glFog: 


void glFogi(GLenum pname, GLint param); 

void glFogf(GLenum pname, GLfloat param) ; 
void glFogiv(GLenum pname, GLint* params); 
void glFogfv(GLenum pname, GLfloat* params); 


The first use of g1Fog shown here is 


glFogfv(GL_FOG_COLOR, flowLight); // Set fog color to match background 


When used with the GL_FOG_COLOR parameter, this function expects a pointer to an array 
of floating-point values that specifies what color the fog should be. Here, we used the 
same color for the fog as the background clear color. If the fog color does not match the 
background (there is no strict requirement for this!), as objects become fogged, they will 
become a fog-colored silhouette against the background. 


The next two lines allow us to specify how far away an object must be before fog is 
applied and how far away the object must be for the fog to be fully applied (object is fog 
color): 


glFogf(GL_FOG_START, 5.0f); // How far away does the fog start 
glFogf(GL_FOG_END, 30.0f); // How far away does the fog stop 


The parameter GL_FOG_START specifies how far away from the eye fogging begins to take 
effect, and GL_FOG_END is the distance from the eye where the fog color completely over- 
powers the color of the object. The transition from start to end is controlled by the fog 
equation, which we set to GL_LINEAR here: 


glFogi(GL_FOG_MODE, GL_LINEAR) ; // Which fog equation do I use? 
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The fog equation calculates a fog factor that varies from 0 to 1 as the distance of the frag- 
ment moves between the start and end distances. OpenGL supports three fog equations: 
GL_LINEAR, GL_EXP, and GL_EXP2. These equations are shown in Table 6.3. 


TABLE 6.3 Three OpenGL Supported Fog Equations 
Fog Mode Fog Equation 


GL_LINEAR f = (end - c) / (end — start) 
GL_EXP f = exp(-d * c) 
GL_EXP2 f = exp(-(d * c)*) 


In these equations, c is the distance of the fragment from the eye point, end is the 
GL_FOG_END distance, and start is the GL_FOG_START distance. The value d is the fog density. 
Fog density is typically set with g1Fogf: 


glFogf(GL_FOG DENSITY, 0.5f); 


Figure 6.7 shows graphically how the fog equation and fog density parameters affect the 
transition from the original fragment color to the fog color. GL_LINEAR is a straight linear 
progression, whereas the GL_EXP and GL_EXP2 equations show two characteristic curves for 
their transitions. The fog density value has no effect with linear fog (GL_LINEAR), but the 
other two curves you see here are generally pulled downward with increasing density 
values. These graphs, for example, show approximately a density value of 0.5. 


0 
Start FOG distance End 


FIGURE 6.7 Fog density equations. 


The distance to a fragment from the eye point can be calculated in one of two ways. The 
first, GL_FRAGMENT_DEPTH, uses the depth value of the fragment itself and can be turned on 
with glFog, as shown here: 


glFogi(GL_FOG_COORD_SRC, GL_FRAGMENT_DEPTH) ; 


Accumulation Buffer 


The second method interpolates the fog depth between vertices and is the default fog 
depth calculation method. This method can be a little faster but can result in a lower 
quality image. Like vertex-based lighting, the more geometry, the better the results will 
look. Once again, g1Fog allows you to set this mode specifically: 


glFogi(GL_FOG_COORD_SRC, GL_FOG_COORD); 


Accumulation Buffer 


In addition to the color, stencil, and depth buffers, OpenGL supports what is called the 
accumulation buffer. This buffer allows you to render to the color buffer, and then instead 
of displaying the results in the window, copy the contents of the color buffer to the accu- 
mulation buffer. Several supported copy operations allow you to repeatedly blend in differ- 
ent ways the color buffer contents with the accumulated contents in the accumulation 
buffer (thus its name!). When you have finished accumulating an image, you can then 
copy the accumulation buffer back to the color buffer and display the results with a buffer 
swap. 


The behavior of the accumulation buffer is controlled by one function: 
void glAccum(GLenumm op, GLfloat value); 
The first parameter specifies which accumulation operation you want to use, and the 


second is a floating-point value that is used to scale the operation. Table 6.4 lists the accu- 
mulation operations supported. 


TABLE 6.4 OpenGL Accumulation Operations 


Operation Description 

GL_ACCUM Scales color buffer values by value and adds them to current contents of the accumu- 
lation buffer. 

GL_LOAD Scales color buffer values by value and replaces the current contents of the accumu- 
lation buffer. 

GL_RETURN Scales the color values from the accumulation buffer by value and then copies the 
values to the color buffer. 

GL_MULT Scales the color values in the accumulation buffer by value and stores the result in 
the accumulation buffer. 

GL_ADD Scales the color values in the accumulation buffer by value and adds the result to the 


current accumulation buffer contents. 


Because of the large amount of memory that must be copied and processed for accumula- 
tion buffer operations, few real-time applications make use of this facility. For non-real- 
time rendering, OpenGL can produce some astonishing effects that you might not expect 
from a real-time API. For example, you can render a scene multiple times and move the 


289 


290 


CHAPTER 6 More on Colors and Materials 


point of view around by a fraction of a pixel each time. Accumulating these multiple 
rendering passes blurs the sharp edges and can produce an entire scene fully antialiased 
with a quality that surpasses anything that can be done with multisampling. You can also 
use this blurring effect to blur the background or foreground of an image and then render 
the object of focus clearly afterward, simulating some depth of field camera effects. 


In our sample program MOTIONBLUR, we will demonstrate yet another use of the accu- 
mulation buffer to create what appears to be a motion blur effect. A moving sphere is 
drawn repeatedly in different positions. Each time it is drawn, it is accumulated to the 
accumulation buffer, with a smaller weight on subsequent passes. The result is a brighter 
red sphere with a trailing ghost-like image of itself following along behind. The output 
from this program is shown in Figure 6.8. 


FIGURE 6.8 Motion-blurred flying sphere. 


Listing 6.4 shows the DrawGeometry function, which draws all the geometry of the scene. 
The RenderScene function then repeatedly calls this function and accumulates the results 
into the accumulation buffer. When finished, the lines 


glAccum(GL_RETURN, 1.0f); 
glutSwapBuffers() ; 


copy the accumulation buffer back to the color buffer and perform the buffer swap. 


Accumulation Buffer 


LISTING 6.4 Using the Accumulation Buffer for Motion Blur 


TTTTATTTTT TTT TTT TAT AT 
// Draw the ground and the revolving sphere 
void DrawGeometry (void) 
{ 
// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 


glPushMatrix(); 
DrawGround(); 


// Place the moving sphere 
glColor3f(1.0f, 0.0f, 0.0f); 
glTranslatef(0.0f, @.5f, -3.5f); 
glRotatef(-(yRot * 2.0f), 0.Of, 1.0f, @.0f); 
glTranslatef(1.0f, 0.0f, 0.0f); 
glutSolidSphere(@.1f, 17, 9); 

glPopMatrix(); 

} 


TITTLLTT TAAL TTT TAA TL AL 
// Called to draw scene. The world is drawn multiple times with each 
// frame blended with the last. The current rotation is advanced each 
// time to create the illusion of motion blur. 
void RenderScene(void) 

{ 

GLfloat fPass; 

GLfloat fPasses = 10.0f; 


// Set the current rotation back a few degrees 
yRot = 35.0f; 


for(fPass = 0.0f; fPass < fPasses; fPass += 1.0f) 


{ 
yRot += .75f; //1.0f / (fPass+1.0f); 


// Draw sphere 
DrawGeometry() ; 


// Accumulate to back buffer 
if(fPass == 0.0f) 

glAccum(GL_LOAD, 0.5f); 
else 
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LISTING 6.4 Continued 7 
glAccum(GL_ACCUM, 0.5f * (1.0f / fPasses)); 


// copy accumulation buffer to color buffer and 
// do the buffer Swap 

glAccum(GL_RETURN, 1.0f); 

glutSwapBuffers(); 

} 


Finally, you must remember to ask for an accumulation buffer when you set up your 
OpenGL rendering context (see the OS-specific chapters for how to perform this task on 
your platform). GLUT also provides support for the accumulation buffer by passing the 
token GLUT_ACCUM to the glutInitDisplayMode function, as shown here: 


glutInitDisplayMode(GLUT DOUBLE } GLUT_RGB | GLUT_DEPTH | GLUT_ACCUM); 


Other Color Operations 


Blending is a powerful OpenGL feature that enables a myriad of special effects algorithms. 
Aside from direct support for blending, fog, and an accumulation buffer, OpenGL also 
supports some other means of tweaking color values and fragments as they are written to 
the color buffer. 


Color Masking 
After a final color is computed and is about to be written to the color buffer, OpenGL 
allows you to mask out one or more of the color channels with the glColorMask function: 


void glColorMask(GLboolean red, GLboolean green, GLboolean blue, 
GLboolean alpha); 


The parameters are for the red, green, blue, and alpha channels, respectively. Passing 
GL_TRUE allows writing of this channel, and GL_FALSE prevents writing to this channel. 


Color Logical Operations 

Many 2D graphics APIs allow binary logical operations to be performed between the 
source and destination colors. OpenGL also supports these types of 2D operations with the 
glLogicOp function: 


void glLogicOp(GLenum op); 
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The logical operation modes are listed in Table 6.5. The logical operation is not enabled by 
default and is controlled, as most states are, with glEnable/glDisable using the value 
GL_COLOR_LOGIG_OP. For example, to turn on the logical operations, you use the following: 


glEnable(GL_COLOR_LOGIC_OP); 


TABLE 6.5 Bitwise Color Logical Operations 


Argument Value Operation 
GL_CLEAR ® 

GL_AND s&d 
GL_AND_REVERSE s & ~-d 
GL_COPY s 
GL_AND_INVERTED ~s&d 
NOOP d 

XOR s xor d 
OR $7.0 
NOR ~(s | d) 
GL_EQUIV ~(s xor d) 
GL_INVERT ~d 
GL_OR_REVERSE s | -d 
GL_COPY_INVERTED -s 
GL_OR_INVERTED -s id 
GL_NAND ~(s & d) 
SET all 1s 


Alpha Testing 

Alpha testing allows you to tell OpenGL to discard fragments whose alpha value fails the 
alpha comparison test. Discarded fragments are not written to the color, depth, stencil, or 
accumulation buffers. This feature allows you to improve performance by dropping values 
that otherwise might be written to the buffers and to eliminate geometry from the depth 
buffer that may not be visible in the color buffer (because of very low alpha values). The 
alpha test value and comparison function are specified with the glAlphaFunc function: 


void glAlphaFunc(GLenum func, GLclampf ref); 


The reference value is clamped to the range 0.0 to 1.0, and the comparison function may 
be specified by any of the constants in Table 6.6. You can turn alpha testing on and off 
with glEnable/glDisable using the constant GL_ALPHA_TEST. The behavior of this function 
is similar to the g1DepthFunc function covered in Chapter 3. 
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TABLE 6.6 Alpha Test Comparison Functions 


Constant Comparison Function 

GL_NEVER Never passes 

GL_ALWAYS Always passes 

GL_LESS Passes if the fragment is less than the reference value 

GL_LEQUAL Passes if the fragment is less than or equal to the reference value 

GL_EQUAL Passes if the fragment is equal to the reference value 

GL_GEQUAL Passes if the fragment is greater than or equal to the reference value 

GL_GREATER Passes if the fragment is greater than the reference value 

GL_NOTEQUAL Passes if the fragment is not equal to the reference value 
Dithering 


Dithering is a simple operation (in principle) that allows a display system with a small 
number of discrete colors to simulate displaying a much wider range of colors. For 
example, the color gray can be simulated by displaying a mix of white and black dots on 
the screen. More white than black dots make for a lighter gray, whereas more black dots 
make a darker gray. When your eye is far enough from the display, you cannot see the 
individual dots, and the blending effect creates the illusion of the color mix. This tech- 
nique is useful for display systems that support only 8 or 16 bits of color information. 
Each OpenGL implementation is free to implement its own dithering algorithm, but the 
effect can be dramatically improved image quality on lower-end color systems. By default, 
dithering is turned on, and can be controlled with glEnable/g1Disable and the constant 
GL_DITHER: 


glEnable(GL_DITHER) ; // Initially enabled 


On higher-end display systems with greater color resolution, the implementation may not 
need dithering, and dithering may not be employed at a potentially considerable perfor- 
mance savings. 


Summary 


In this chapter, we took color beyond simple shading and lighting effects. You saw how to 
use blending to create transparent and reflective surfaces and create antialiased points, 
lines, and polygons with the blending and multisampling features of OpenGL. You also 
were introduced to the accumulation buffer and saw at least one common special effect 
that it is normally used for. Finally, you saw how OpenGL supports other color manipula- 
tion features such as color masks, bitwise color operations, and dithering, and how to use 
the alpha test to discard fragments altogether. Now we progress further in the next chapter 
from colors, shading, and blending to operations that incorporate real image data. 


Reference 


Included in the sample directory on the CD-ROM for this chapter, you'll find an update of 
the Sphere World example from Chapter 5. You can study the source code to see how we 
have incorporated many of the techniques from this chapter to add some additional depth 
queuing to the world with fog, partially transparent shadows on the ground, and fully 
antialiased rendering of all geometry. 


Reference 

glAccum 

Purpose: Operates on the accumulation buffer to establish pixel values. 
Include File: <GL/gl.h> 

Syntax: 


void glAccum(GLenum op, GLfloat value); 


Description: This function operates on the accumulation buffer. Except for GL_RETURN, 
color values are scaled by the value parameter and added or stored into 
the accumulation buffer. For GL_RETURN, the accumulation buffer’s color 
values are scaled by the value parameter and stored in the current color 


buffer. 

Parameters: 

op GLenum: The accumulation function to apply. These functions are listed in 
Table 6.4. 

value GLfloat: The fractional amount of accumulation to perform. 

Returns: None. 

See Also: glClearAccum 

glBlendColor 

Purpose: Sets the constant blending color that is optionally used by the blending 
equation. 


Include File: <gl/gl.h> 
Syntax: 
void glBlendcolor(GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha); 


Description: This function sets the blending color to be used when the blending equa- 
tion is set to use the constant blending color for either the source or 
destination factors. These blending factors are GL_CONSTANT_COLOR, 
GL_ONE_MINUS_CONSTANT_COLOR, GL_CONSTANT_ALPHA, and 
GL_ONE_MINUS_CONSTANT_ALPHA. 
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Parameters: 

red GLClampf: The constant blending color’s red intensity. 

green GLClampf: The constant blending color’s green intensity. 

blue GLClampf: The constant blending color’s blue intensity. 

alpha GLClampf: The constant blending color’s alpha intensity. 

Returns: None. 

See Also: glBlendEquation, glBlendFunc, glBlendFuncSeparate 
glBlendEquation 

Purpose: Sets the blending equation to be used for color blending operations. 


Include File: <gl/gl.h> 
Syntax: 
void glBlendEquation(GLenum mode) ; 


Description: When blending is enabled, the source and destination colors are 
combined. The g1BlendFunc function determines the weighting factors 
for these two colors, but this function selects which equation will be used 
to derive the new color value. The valid equations and their meanings are 
given in Table 6.2. The default blending equation is GL_FUNC_ADD. 


Parameters: 

mode GLenum: One of the values specified in Table 6.2. 

Returns: None. 

See Also: glBlendColor, g1BlendFunc, gl1BlendFuncSeparate 
glBlendFunc 

Purpose: Sets color blending function’s source and destination factors. 


Include File: <gl/gl.h> 
Syntax: 
void glBlendFunc(GLenum sfactor, GLenum dfactor) ; 


Description: This function sets the source and destination blending factors for color 
blending. You must call glEnable(GL_BLEND) to enable color blending. 
The default settings for blending are g1BlendFunc(GL_ONE, GL_ZERO). 
The list of valid blending factors is given in Table 6.1. 


Parameters: 
sfactor GLenum: The source color’s blending function. 
dfactor GLenum: The destination color’s blending function. 


Reference 


Returns: None. 

See Also: glBlendColor, glBlendEquation, glBlendFuncSeparate 

glBlendFuncSeparate 

Purpose: Allows separate blending factors to be applied to the RGB color and alpha 
value. 


Include File: <gl/gl.h> 
Syntax: 


void glBlendFuncSeparate(GLenum srcRGB, GLenum dstAGB, GLenum srcAlpha, 
GLenum dstAlpha) ; 


Description: This function allows a separate weighting factor to be applied to the color 
(RGB) portion of a fragment and its alpha component. This applies to 
both source and destination color values. The list of valid blending 
factors is given in Table 6.1. 


Parameters: 

srcRGB GLenum: The source’s RGB blending factor. 
dstRGB GLenum: The destination’s RGB blending factor. 
srcAlpha GLenum: The source’s alpha blending factor. 
dstAlpha GLenum: The destination’s alpha blending factor. 
Returns: None. 

See Also: glBlendColor, glBlendEquation, g1BlendFunc 
glClearAccum 

Purpose: Specifies the color values used to clear the accumulation buffer. 
Include File: <gl/gl.h> 

Syntax: 


void glClearAccum(GLfloat red, GLfloat green, GLfloat blue, GLfloat alpha); 


Description: This function specifies the color values to be used when clearing the 
accumulation buffer. The accumulation buffer is cleared by passing 
GL_ACCUM_BUFFER_BIT to the glClear function. 


Parameters: 

red GLfloat: Value of the red color component. 
green GLfloat: Value of the green color component. 
blue GLfloat: Value of the blue color component. 


alpha GLfloat: Value of the alpha color component. 
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Returns: None. 

See Also: glAccum, glClear 

glColorMask 

Purpose: Masks or enables writing to the color buffer. 


Include File: <gl/gl.h> 
Syntax: 
void glColorMask(GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha) ; 


Description: Writing to the color buffer may be masked out by setting the color mask 
with this function. Pass GL_TRUE for any color channel to allow writing, 
and GL_FALSE to prevent changes or writes. 


Parameters: 

red GLboolean: Enable or disable writes to the red component of the color 
buffer. 

green GLboolean: Enable or disable writes to the green component of the color 
buffer. 

blue GLboolean: Enable or disable writes to the blue component of the color 
buffer. 

alpha GLboolean: Enable or disable writes to the alpha component of the color 
buffer. 

Returns: None. 

See Also: glDepthMask, glLogicOp, glStencilMask 

glFog 

Purpose: Controls the behavior of fog. 


Include File: <gl/gl.h> 

Syntax: 

void glFogf(GLenum pname, GLfloat param) ; 
void glFogfv(GLenum pname, GLfloat *params) ; 
void glFogi(GLenum pname, GLint param) ; 
void glFogiv(GLenum pname, GLint *params) ; 


Description: The g1Fog functions set the various fog parameters. To render using fog, 
you must enable fog with glEnable(GL_FOG). 


Parameters: 


pname 


param 


params 


Returns: 
See Also: 


glLogicOp 
Purpose: 
Include File: 
Syntax: 


Reference 


GLenum: The parameter to set. Valid values are as follows: 
GL_FOG_COLOR: Specifies the fog color as an array of four floats (RGBA). 


GL_FOG_COORD_SRC: Determines how the fog coordinates are calculated. 
Must be either GL_FOG_COORD (vertex-interpolated fog) or GL_FOG_FRAG- 
MENT_DEPTH (using the fragment’s depth value). 


GL_FOG_DENSITY: Specifies the fog density. 
GL_FOG_END: Specifies the maximum distance at which fog is applied. 


GL_FOG_MODE: Specifies the fog mode. Must be either GL_LINEAR, GL_EXP, 
or GL_EXP2. 


GL_FOG_START: Specifies the distance at which fog begins to be applied. 
GLfloat, GLint: The parameter value. 


GLfloat *,GLint *: A pointer to the parameter array as either floats or 
ints. 


None. 
glEnable 


Selects a logical operation to be performed on color writes. 
<gl/gl.h> 


void glLogicOp(GLenum op); 


Description: 


Parameters: 
op 


Returns: 
See Also: 


This function sets a bitwise logical operation to be performed between an 
incoming color value (source) and the existing (destination) color in the 
color buffer. By default, the logic operation is disabled and must be 
turned on with glEnable(GL_COLOR_LOGIC_OP). 


GLenum: Specifies the logical operation to be performed. Any constant 
from Table 6.5 may be used. 


None. 
glColorMask 
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glSampleCoverage 
Purpose: Sets how alpha values are interpreted when computing multisampling 
coverage. 


Include File: <gl/gl.h> 
Syntax: 
void glSampleCoverage(GLclampf value, GLboolean invert) ; 


Description: Normally, the multisampling operation uses only RGB values to calculate 
fragment coverage. However, if you enable either 
GL_SAMPLE_ALPHA_TO_ONE, GL_SAMPLE_ALPHA_TO_COVERAGE, or 
GL_SAMPLE_COVERAGE, OpenGL will use the alpha component for coverage 
calculations. This function is used to set a value that is ANDed (or 
inverted and ANDed) with the fragment coverage value when either 
GL_SAMPLE_ALPHA_TO_COVERAGE or GL_SAMPLE_COVERAGE is enabled. 


Parameters: 

value GLclampf: Temporary coverage value used if GL_ALPHA_TO_COVERAGE or 
GL_SAMPLE_COVERAGE has been enabled. 

invert GLboolean: Set to true to indicate the temporary coverage value should be 
bitwise inverted before it is used. 

Returns: None. 


See Also: glutInitDisplayMode 


CHAPTER 7 


Imaging with OpenGL 


by Richard S. Wright, Jr. 


WHAT YOU’LL LEARN IN THIS CHAPTER: 


How To Functions You'll Use 

Set the raster position glRasterPos, glWindowPos 
Draw bitmaps glBitmap 

Read and write color images glReadPixels, glDrawPixels 
Magnify, shrink, and flip images glPixelZoom 

Set up operations on colors glPixelTransfer, glPixelMap 
Perform color substitutions glColorTable 

Perform advanced image filtering glConvolutionFilter2D 
Collect statistics on images glHistogram, glGetHistogram 


In the preceding chapters, you learned the basics of OpenGL’s acclaimed 3D graphics capa- 
bilities. Until now, all output has been the result of three-dimensional primitives being 
transformed and projected to 2D space and finally rasterized into the color buffer. 
However, OpenGL also supports reading and writing directly from and to the color buffer. 
This means image data can be read directly from the color buffer into your own memory 
buffer where it can be manipulated or written to a file. This also means you can derive or 
read image data from a file and place it directly into the color buffer yourself. OpenGL 
goes beyond merely reading and writing 2D images and has support for a number of 
imaging operations that can be applied automatically during reading and writing opera- 
tions. This chapter is all about OpenGL’s rich but sometimes overlooked 2D capabilities. 


Bitmaps 
In the beginning, there were bitmaps. And they were...good enough. The original elec- 


tronic computer displays were monochrome (one color), typically green or amber, and 
every pixel on the screen had one of two states: on or off. Computer graphics were simple 
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in the early days, and image data was represented by bitmaps—a series of ones and zeros 
representing on and off pixel values. In a bitmap, each bit in a block of memory corre- 
sponds to exactly one pixel’s state on the screen. We introduced this idea in the “Filling 
Polygons, or Stippling Revisited” section in Chapter 3, “Drawing in Space: Geometric 
Primitives and Buffers.” Bitmaps can be used for masks (polygon stippling), fonts and 
character shapes, and even two-color dithered images. Figure 7.1 shows an image of a 
horse represented as a bitmap. Even though only two colors are used (black and white 
dots), the representation of a horse is still apparent. Compare this image with the one in 
Figure 7.2, which shows a grayscale image of the same horse. In this pixelmap, each pixel 
has one of 256 different intensities of gray. We discuss pixelmaps further in the next 
section. The term bitmap is often applied to images that contain grayscale or full color 
data. This description is especially common on the Windows platform, and many would 
argue that, strictly speaking, this is a misapplication of the term. In this book, we use the 
term bitmap to mean a true binary map of on and off values, and we use the term pixelmap 
(or frequently pixmap for short) for image data that contains color or intensity values for 
each pixel. 


FIGURE 7.1 A bitmapped image of a horse. 
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A Bitmapped Sample 

The sample program BITMAPS is shown in Listing 7.1. This program uses the same bitmap 
data used in Chapter 3 for the polygon stippling sample that represents the shape of a 
small campfire arranged as a pattern of bits measuring 32x32. Remember that bitmaps are 
built from the bottom up, which means the first row of data actually represents the 
bottom row of the bitmapped image. This program creates a 512x512 window and fills the 
window with 16 rows and columns of the campfire bitmap. The output is shown in Figure 
7.3. Note that the ChangeSize function sets an orthographic projection matching the 
window’s width and height in pixels. 


FIGURE 7.2. A pixmap image of a horse. 
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FIGURE 7.3. The 16 rows and columns of the campfire bitmap. 


LISTING 7.1 The BITMAPS Sample Program 


#include "../../Common/OpenGLSB.h" // System and OpenGL Stuff 
#include "../../Common/GLTools.h" // OpenGL toolkit 


// Bitmap of camp fire 
GLubyte fire[128] = { 0x00, @x@0, 0x00, 0x00, 
Q@x@0, @x@0, Ox@0, 2x00, 
@x00, @x@0, Ox@0, 0x00, 
@x00, @x@0, Ox@0, 0x00, 
@x00, @x0@0, Ox00, 0x00, 
Qx00, Ox@0, Ox00, 0x00, 
@x@0, Ox00, @x@0, Oxcd, 
Q@x@0, Ox00, Ox01, Oxfe, 
Q@x®0, Ox00, Ox07, Oxfd, 


LISTING 7.1 Continued 


Bitmaps 


OxOf, O@x00, Oxif, Oxed, 
Oxif, x80, Ox1f, Oxcd, 
OxOf, OxcO, Ox3f, 0x80, 
@x07, @xeQ, Ox7e, 0x00, 
@x03, Oxf, Oxff, 0x80, 
@x03, Oxf5, Oxff, Oxed, 
@x07, Oxfd, Oxff, Oxf8, 
Oxif, Oxfc, Oxff, Oxe8, 
Oxff, Oxe3, Oxbf, Ox70, 
@xde, 0x80, Oxb7, 0x00, 
0x71, Ox10, Ox4a, 0x80, 
@x03, 0x10, Ox4e, 0x40, 
@x@2, 0x88, @x8c, 0x20, 
@x@5, 0x05, 0x04, 0x40, 
@x02, Ox82, 0x14, 0x40, 
@x02, 0x40, 0x10, 0x80, 
@x02, 0x64, Oxta, 0x80, 
@x@0, Ox92, Ox29, 0x00, 
@x00, Oxb®@, 0x48, 0x00, 
@x00, Oxc8, @x90, 0x00, 
@x@Q, Ox85, Ox10, 0x00, 
@x@0, Ox03, @x00, 0x00, 
@x@0, O@x00, Ox10, Ox0d }; 


LLTTTLTTTT TTT TT TT 
// This function does any needed initialization on the rendering 
// context. 
void SetupRC() 

{ 

// Black background 

glClearColor(0.0f, 0.0f, 0.O0f, 0.0f); 

} 


LITT TTT TTL 
// Set coordinate system to match window coordinates 
void ChangeSize(int w, int h) 
{ 
// Prevent a divide by zero, when window is too short 
// (you can't make a window of zero width). 
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LISTING 7.1 Continued 


if(h == 0) 
h= 1; 


glViewport(®, 0, w, h); 


// Reset the coordinate system before modifying 
glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 


// Pseudo window coordinates 
gluOrtho2D(0.0, (GLfloat) w, 0.0f, (GLfloat) h); 


glMatrixMode(GL_MODELVIEW) ; 
glLoadIdentity(); 
} 


FELLTTTTT TTT TTT TTT TTT Ak 
// Called to draw scene 
void RenderScene(void) 

{ 


int x, y; 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Set color to white 
glColor3f(1.0f, 1.0f, 1.0f); 


// Loop through 16 rows and columns 
for(y = 0; y < 16; y++) 
{ 
// Set raster position for this "square" 
glRasterPos2i(®, y * 32); 
for(x = 0; x < 16; xt+) 
// Draw the "fire" bitmap, advance raster position 
glBitmap(32, 32, 0.0, 0.0, 32.0, 0.0, fire); 


// Do the buffer Swap 
glutSwapBuffers() ; 


Bitmaps 


LISTING 7.1 Continued 
} 


TILTTLTTT TTT TAT TAA TA A TL 
// Main program entrypoint 
int main(int argc, char* argv[]) 
{ 
glutInit(&argc, argv); 
glutInitDisplayMode(GLUT_RGB | GLUT_DOUBLE) ; 
glutInitWindowSize(512, 512); 
glutCreateWindow( "OpenGL Bitmaps") ; 
glutReshapeFunc(ChangeSize) ; 
glutDisplayFunc(RenderScene) ; 


SetupRC(); 
glutMainLoop(); 


return 0; 


} 


Setting the Raster Position 
The real meat of the BITMAPS sample program occurs in the RenderScene function where 
a set of nested loops draws 16 rows of 16 columns of the campfire bitmap: 


// Loop through 16 rows and columns 
for(y = 0; y < 16; y++) 
{ 
// Set raster position for this “square” 
glRasterPos2i(®, y * 32); 
for(x = 0; x < 16; x++) 
// Draw the "fire" bitmap, advance raster position 
glBitmap(32, 32, 0.0, 0.0, 32.0, 0.0, fire); 
} 


The first loop (y variable) steps the row from 0 to 16. The following function call sets the 
raster position to the place where you want the bitmap drawn: 


glRasterPos2i(®, y * 32); 
The raster position is interpreted much like a call to g1Vertex in that the coordinates are 


transformed by the current modelview and projection matrices. The resulting window 
position becomes the current raster position. All rasterizing operations (bitmaps and 
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pixmaps) occur with the current raster position specifying the image’s lower-left corner. If 
the current raster position falls outside the window’s viewport, it is invalid, and any 
OpenGL operations that require the raster position will fail. 


In this example, we deliberately set the OpenGL projection to match the window dimen- 
sions so that we could use window coordinates to place the bitmaps. However, this tech- 
nique may not always be convenient, so OpenGL provides an alternative function that 
allows you to set the raster position in window coordinates without regard to the current 
transformation matrix or projection: 


void glWindowPos2i(GLint x, GLint y); 


The glWindowPos function comes in two- and three-argument flavors and accepts integers, 
floats, doubles, and short arguments much like g1lVertex. See the reference section for a 
complete breakdown. 


One important note about the raster position is that the color of the bitmap is set when 
either glRasterPos or glWindowPos is called. This means that the current color previously 
set with glColor is bound to subsequent bitmap operations. Calls to g1Color made after 
the raster position is set will have no effect on the bitmap color. 


Drawing the Bitmap 
Finally, we get to the command that actually draws the bitmap into the color buffer: 


glBitmap(32, 32, 0.0, 0.0, 32.0, 0.0, fire); 


The g1Bitmap function copies the supplied bitmap to the color buffer at the current raster 
position and optionally advances the raster position all in one operation. This function 
has the following syntax: 


void glBitmap(GLsize width, GLsize height, GLfloat xorig, GLfloat yorig, 
GLfloat xmove, GLfloat ymove, GLubyte *bitmap); 


The first two parameters, width and height, specify the width and height of the bitmap 
(in bits). The next two parameters, xorig and yorig, specify the floating-point origin of 
the bitmap. To begin at the lower-left corner of the bitmap, specify 0.0 for both of these 
arguments. Then xmove and ymove specify an offset in pixels to move the raster position in 
the x and y directions after the bitmap is rendered. Note that these four parameters are all 
in floating-point units. The final argument, bitmap, is simply a pointer to the bitmap data. 
Note that when a bitmap is drawn, only the 1s in the image create fragments in the color 
buffer; Os have no effect on anything already present. 


Pixel Packing 


Pixel Packing 


Bitmaps and pixmaps are rarely packed tightly into memory. On many hardware plat- 
forms, each row of a bitmap or pixmap should begin on some particular byte-aligned 
address for performance reasons. Most compilers automatically put variables and buffers at 
an address alignment optimal for that architecture. OpenGL, by default, assumes a 4-byte 
alignment, which is appropriate for many systems in use today. The campfire bitmap used 
in the preceding example was tightly packed, but it didn’t cause problems because the 
bitmap just happened to also be 4-byte aligned. Recall that the bitmap was 32 bits wide, 
exactly 4 bytes. If we had used a 34-bit wide bitmap (only two more bits), we would have 
had to pad each row with an extra 30 bits of unused storage, for a total of 64 bits (8 bytes 
is evenly divisible by 4). Although this may seem like a waste of memory, this arrange- 
ment allows most CPUs to more efficiently grab blocks of data (such as a row of bits for a 
bitmap). 


You can change how pixels for bitmaps or pixmaps are stored and retrieved by using the 
following functions: 


void glPixelStorei(GLenum pname, GLint param) ; 
void glPixelStoref(GLenum pname, GLfloat param); 


If you want to change to tightly packed pixel data, for example, you make the following 
function call: 


glPixelStorei(GL_UNPACK_ALIGNMENT, 1); 


GL_UNPACK_ALIGNMENT specifies how image data OpenGL will unpack from the data buffer. 
Likewise, you can use GL_PACK_ALIGNMENT to tell OpenGL how to pack data being read 
from the color buffer and placed in a user-specified memory buffer. The complete list of 
pixel storage modes available through this function is given in Table 7.1 and explained in 
more detail in the reference section. 


TABLE 7.1 glPixelStore Parameters 


Parameter Name Type Initial Value 
GL_PACK_SWAP_BYTES GLboolean GL_FALSE 
GL_UNPACK_SWAP_BYTES GLboolean GL_FALSE 
GL_PACK_LSB_FIRST GLboolean GL_FALSE 
GL_UNPACK_LSB_FIRST GLboolean GL_FALSE 
GL_PACK_ROW_LENGTH GLint 0 
GL_UNPACK_ROW_LENGTH GLint 0 
GL_PACK_SKIP_ROWS GLint 0 
GL_UNPACK_SKIP_ROWS GLint 0 
GL_PACK_SKIP_PIXELS GLint 0 
GL_UNPACK_SKIP_PIXELS GLint 0 
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TABLE 7.1 Continued 


Parameter Name Type Initial Value 
GL_PACK_ALIGNMENT GLint 4 
GL_UNPACK_ALIGNMENT GLint 4 
GL_PACK_IMAGE_HEIGHT GLint 0 
GL_UNPACK_IMAGE_HEIGHT GLint 0 
GL_PACK_SKIP_IMAGES GLint 0 
GL_UNPACK_SKIP_IMAGES Glint 0 
Pixmaps 


Of more interest and somewhat greater utility on today’s full-color computer systems are 
pixmaps. A pixmap is similar in memory layout to a bitmap; however, each pixel may be 
represented by more than one bit of storage. Extra bits of storage for each pixel allow 
either intensity (sometimes referred to as Juminance values) or color component values to 
be stored. You draw pixmaps at the current raster position just like bitmaps, but you draw 
them using a new function: 


void glDrawPixels(GLsizei width, GLsizei height, GLenum format, 
GLenum type, const void *pixels); 


The first two arguments specify the width and height of the image in pixels. The third 
argument specifies the format of the image data, followed by the data type of the data and 
finally a pointer to the data itself. Unlike g1Bitmap, this function does not update the 
raster position and is considerably more flexible in the way you can specify image data. 


Each pixel is represented by one or more data elements contained at the *pixel pointer. 
The color layout of these data elements is specified by the format parameter using one of 
the constants listed in Table 7.2. 


TABLE 7.2 OpenGL Pixel Formats 


Constant Description 

GL_RGB Colors are in red, green, blue order. 

GL_RGBA Colors are in red, green, blue, alpha order. 
GL_BGR/GL_BGR_EXT Colors are in blue, green, red order. 

GL_BGRA/GL_BGRA_EXT Colors are in blue, green, red, alpha order. 

GL_RED Each pixel contains a single red component. 

GL_GREEN Each pixel contains a single green component. 

GL_BLUE Each pixel contains a single blue component. 

GL_ALPHA Each pixel contains a single alpha component. 

GL_LUMINANCE Each pixel contains a single luminance (intensity) component. 
GL_LUMINANCE_ALPHA Each pixel contains a luminance followed by an alpha component. 
GL_STENCIL_INDEX Each pixel contains a single stencil value. 


GL_DEPTH_COMPONENT Each pixel contains a single depth value. 
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Two of the formats, GL_STENCIL_INDEX and GL_DEPTH_COMPONENT, are used for reading and 
writing directly to the stencil and depth buffers. The type parameter interprets the data 
pointed to by the *pixels parameter. It tells OpenGL what data type within the buffer is 
used to store the color components. The recognized values are specified in Table 7.3. 


TABLE 7.3 Data Types for Pixel Data 


Constant Description 

GL_UNSIGNED_BYTE Each color component is an 8-bit unsigned integer 
GL_BYTE Signed 8-bit integer 

GL_BITMAP Single bits, no color data; same as g1Bitmap 
GL_UNSIGNED_SHORT Unsigned 16-bit integer 

GL_SHORT Signed 16-bit integer 

GL_UNSIGNED_INT Unsigned 32-bit integer 

GL_INT Signed 32-bit integer 

GL_FLOAT Single precision float 

GL_UNSIGNED_BYTE_3 2 2 Packed RGB values 
GL_UNSIGNED_BYTE_2_3_3_REV Packed RGB values 

GL_UNSIGNED_SHORT_5 6 5 Packed RGB values 

GL_UNSIGNED_SHORT_5 6 5 REV Packed RGB values 
GL_UNSIGNED_SHORT_4_4 4 4 Packed RGBA values 
GL_UNSIGNED_SHORT_4_4 4 4 REV Packed RGBA values 
GL_UNSIGNED_SHORT_5_5_5_1 Packed RGBA values 
GL_UNSIGNED_SHORT_1_5_5 5 REV Packed RGBA values 

GL_UNSIGNED_INT_8 8 8 8 Packed RGBA values 

GL_UNSIGNED_INT_8_8 8 8 REV Packed RGBA values 
GL_UNSIGNED_INT_10_10_10 2 Packed RGBA values 
GL_UNSIGNED_INT_2 10 10 10 REV Packed RGBA values — 


Packed Pixel Formats 

The packed formats listed in Table 7.3 were introduced in OpenGL 1.2 as a means of 
allowing image data to be stored in a more compressed form that matched a range of color 
graphics hardware. Display hardware designs could save memory or operate faster on a 
smaller set of packed pixel data. These packed pixel formats are still found on some PC 
hardware and may continue to be useful for future hardware platforms. 


The packed pixel formats compress color data into as few bits as possible, with the number 
of bits per color channel shown in the constant. For example, the 
GL_UNSIGNED_BYTE_3_3 2 format stores three bits of the first component, three bits of the 
second component, and two bits of the third component. Remember, the specific compo- 
nents (red, green, blue, and alpha) are still ordered according to the format parameter of 
glDrawPixels. The components are ordered from the highest bits (most significant bit or 
MSB) to the lowest (least significant bit or LSB). GL_UNSIGNED_BYTE_2_3_3_REV reverses this 
order and places the last component in the top two bits, and so on. Figure 7.4 shows 


312 CHAPTER 7_ Imaging with OpenGL 


graphically the bitwise layout for these two arrangements. All the other packed formats are 
interpreted in the same manner. 


| UNSIGNED_BYTE_3 3.2 
| ee TO ae 
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UNSIGNED_BYTE_2_3.3. REV 
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FIGURE 7.4 Sample layout for two packed pixel formats. 


A More Colorful Example 


Now it’s time to put your new pixel knowledge to work with a more colorful and realistic 
rendition of a campfire. Figure 7.5 shows the output of the next sample program, IMAGE- 
LOAD. This program loads an image, fire.tga, and uses glDrawPixels to place the image 
directly into the color buffer. This program is almost identical to the BITMAPS sample 
program with the exception that the color image data is read from a targa image file (note 
the .tga file extension) using the glTools function gltLoadTGA and then drawn with a call 
to glDrawPixels instead of g1Bitmap. The function that loads the file and displays it is 
shown in Listing 7.2. 


FIGURE 7.5 A campfire image loaded from a file. 
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LISTING 7.2 The RenderScene Function to Load and Display the Image File 


// Called to draw scene 
void RenderScene(void) 
{ 
GLubyte *pImage = NULL; 
GLint iWidth, iHeight, iComponents; 
GLenum eFormat; 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Targas are 1 byte aligned 
glPixelStorei(GL_UNPACK_ALIGNMENT, 1); 


// Load the TGA file, get width, height, and component/format information 
pImage = gltLoadTGA("fire.tga", &iWidth, &iHeight, &iComponents, &eFormat) ; 


// Use Window coordinates to set raster position 
glRasterPos2i(@, 0); 


// Draw the pixmap 
if(pImage != NULL) 
glDrawPixels(iWidth, iHeight, eFormat, GL_UNSIGNED_BYTE, pImage) ; 


// Don't need the image data anymore 
free(pImage) ; 


// Do the buffer Swap 
glutSwapBuffers() ; 
} 


Note the call that reads the targa file: 


// Load the TGA file, get width, height, and component/format information 
pImage = gltLoadTGA("fire.tga", &iWidth, &iHeight, &iComponents, &eFormat) ; 


We use this function frequently in other sample programs when the need arises to load 
image data from a file. The first argument is the filename (with the path if necessary) of 
the targa file to load. The targa image format is a well-supported and common image file 
format. Unlike JPEG files, targa files (usually) store an image in its uncompressed form. 
The gltLoadTGA function opens the file and then reads in and parses the header to deter- 
mine the width, height, and data format of the file. The number of components can be 
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one, three, or four for luminance, RGB, or RGBA images, respectively. The final parameter 
is a pointer to a GLenum that receives the corresponding OpenGL image format for the file. 
If the function call is successful, it returns a newly allocated pointer to the image data read 
directly from the file. If the file is not found, or some other error occurs, the function 
returns NULL. The complete listing for the g1tLoadTGA function is given in Listing 7.3. 


LISTING 7.3 The gltLoadTGA Function to Load Targa Files for Use in OpenGL 


FULTTTTTT TTT TTT TTT A TTT Tk 
// Allocate memory and load targa bits. Returns pointer to new buffer, 
// height, and width of texture, and the OpenGL format of data. 
// Call free() on buffer when finished! 
// This only works on pretty vanilla targas... 8, 24, or 32 bit color 
// only, no palettes, no RLE encoding. 
GLbyte *gltLoadTGA(const char *szFileName, 

GLint *iWidth, GLint *iHeight, 

GLint *iComponents, GLenum *eFormat) 


{ 

FILE *pFile; // File pointer 

TGAHEADER tgaHeader; // TGA file header 
unsigned long lImageSize; // Size in bytes of image 
short sDepth; // Pixel depth; 

GLbyte *pBits = NULL; // Pointer to bits 


// Default/Failed values 
*iWidth = 0; 

*iHeight = 0; 

*eFormat = GL_BGR_EXT; 
*iComponents = GL_RGB8; 


// Attempt to open the file 
pFile = fopen(szFileName, "“rb"); 
if(pFile == NULL) 

return NULL; 


// Read in header (binary) 
fread(&tgaHeader, 18/* sizeof (TGAHEADER)*/, 1, pFile); 


// Do byte swap for big vs little endian 
#ifdef _ APPLE __ 
BYTE_SWAP(tgaHeader.colorMapStart) ; 
BYTE_SWAP (tgaHeader.colorMapLength) ; 
BYTE_SWAP(tgaHeader.xstart) ; 
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LISTING 7.3 Continued 


BYTE_SWAP(tgaHeader.ystart) ; 

BYTE_SWAP(tgaHeader.width) ; 

BYTE_SWAP(tgaHeader. height) ; 
#endif 


// Get width, height, and depth of texture 
*iWidth = tgaHeader.width; 

*iHeight = tgaHeader.height; 

sDepth = tgaHeader.bits / 8; 


// Put some validity checks here. Very simply, I only understand 

// or care about 8, 24, or 32 bit targas. 

if(tgaHeader.bits != 8 && tgaHeader.bits != 24 && tgaHeader.bits != 32) 
return NULL; 


// Calculate size of image buffer 
lImageSize = tgaHeader.width * tgaHeader.height * sDepth; 


// Allocate memory and check for success 
pBits = malloc(lImageSize * sizeof (GLbyte) ); 
if(pBits == NULL) 

return NULL; 


// Read in the bits 
// Check for read error. This should catch RLE or other 
// weird formats that I don't want to recognize 
if(fread(pBits, lImageSize, 1, pFile) != 1) 

{ 

free(pBits) ; 

return NULL; 

} 


// Set OpenGL format expected 
switch(sDepth) 
{ 
case 3: // Most likely case 
*eFormat = GL_BGR_EXT; 
*iComponents = GL_RGB8; 
break; 
case 4: 
*eFormat = GL_BGRA_EXT; 
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LISTING 7.3. Continued 


*iComponents = GL_RGBA8; 
break; 

case 1: 
*eFormat = GL_LUMINANCE; 
*iComponents = GL_LUMINANCES8; 
break; 


}; 


// Done with File 
fclose(pFile); 


// Return pointer to image data 
return pBits; 


} 


You may notice that the number of components is not set to the integers 1, 3, or 4, but 
GL_LUMINANCE8, GL_RGB8, and GL_RGBA8. OpenGL recognizes these special constants as a 
request to maintain full image precision internally when it manipulates the image data. 
For example, for performance reasons, some OpenGL implementations may down-sample 
a 24-bit color image to 16 bits internally. This is especially common for texture loads (see 
Chapter 8, “Texture Mapping: The Basics”) on many implementations where the display 
output color resolution is only 16 bits, but a higher bit depth image is loaded. These 
constants are requests to the implementation to store and use the image data as supplied 
at their full 8-bit per channel color depth. 


Moving Pixels Around 


Writing pixel data to the color buffer can be very useful in and of itself, but you can also 
read pixel data from the color buffer and even copy data from one part of the color buffer 
to another. The function to read pixel data works just like g1DrawPixels, but in reverse: 


void glReadPixels(GLint x, GLint y, GLsizei width, GLsizei height, 
GLenum format, GLenum type, const void *pixels); 


You specify the x and y in window coordinates of the lower-left corner of the rectangle to 
read followed by the width and height of the rectangle in pixels. The format and type 
parameters are the format and type you want the data to have. If the color buffer stores 
data differently than what you have requested, OpenGL will take care of the necessary 
conversions. This capability can be very useful, especially after you learn a couple of magic 
tricks that you can do during this process using the glPixelTransfer function (coming up 
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in the “Pixel Transfer” section). The pointer to the image data, *pixels, must be valid and 
must contain enough storage to contain the image data after conversion, or you will likely 
get a nasty memory exception at runtime. 


Copying pixels from one part of the color buffer to another is also easy, and you don’t 
have to allocate any temporary storage during the operation. First, set the raster position 
using glRasterPos or glWindowPos to the destination corner (remember, the lower-left 
corner) where you want the image data copied. Then use the following function to 
perform the copy operation: 


void glCopyPixels(GLint x, GLint y, GLsizei width, 
GLsizei height, GLenum type); 


The x and y parameters specify the lower-left corner of the rectangle to copy, followed by 
the width and height in pixels. The type parameter should be GL_COLOR to copy color 
data. You can also use GL_DEPTH and GL_STENCIL here, and the copy will be performed in 
the depth or stencil buffer instead. Moving depth and stencil values around can also be 
useful for some rendering algorithms and special effects. 


By default, all these pixel operations operate on the back buffer for double-buffered 
rendering contexts, and the front buffer for single-buffered rendering contexts. You can 
change the source or destination of these pixel operations by using these two functions: 


void glDrawBuffer(GLenum mode) ; 
void glReadBuffer(GLenum mode) ; 


The glDrawBuffer function affects where pixels are drawn by either g1DrawPixels or 
glCopyPixels operations. You can use any of the valid buffer constants discussed in 
Chapter 3: GL_NONE, GL_FRONT, GL_BACK, GL_FRONT_AND_BACK, GL_FRONT_LEFT, 
GL_FRONT_RIGHT, and so on. 


The glReadBuffer function accepts the same constants and sets the target color buffer for 
read operations performed by glReadPixels or glCopyPixels. 


Saving Pixels 

You now know enough about how to move pixels around to write another useful function 
for the glTools library. A counterpart to the targa loading function, gltLoadTGA, is 
gltWriteTGA. This function reads the color data from the front color buffer and saves it to 
an image file in the targa file format. You use this function in the next section when you 
start playing with some interesting OpenGL pixel operations. The complete listing for the 
gltWriteTGA function is shown in Listing 7.4. 
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LISTING 7.4 The gltWriteTGA Function to Save the Screen as a Targa File 


TTTTTTTTT TTT TAT TLL 
// Capture the current viewport and save it as a targa file. 

// Be sure and call SwapBuffers for double buffered contexts or 

// glFinish for single buffered contexts before calling this function. 
// Returns @ if an error occurs, or 1 on success. 

GLint gltWriteTGA(const char *szFileName) 


{ 

FILE *pFile; // File pointer 

TGAHEADER tgaHeader; // TGA file header 

unsigned long limageSize; // Size in bytes of image 

GLbyte *pBits = NULL; // Pointer to bits 

GLint iViewport[4]; // Viewport in pixels 

GLenum lastBuffer; // Storage for the current read buffer setting 


// Get the viewport dimensions 
glGetIntegerv(GL_VIEWPORT, iViewport) ; 


// How big is the image going to be (targas are tightly packed) 
lImageSize = iViewport[2] * 3 * iViewport[3]; 


// Allocate block. If this doesn't work, go home 
pBits = (GLbyte *)malloc(lImageSize) ; 
if(pBits == NULL) 

return Q; 


// Read bits from color buffer 
glPixelStorei(GL_PACK_ALIGNMENT, 1); 
glPixelStorei(GL_PACK_ROW_LENGTH, 0); 
glPixelStorei(GL_PACK_SKIP_ROWS, Q); 
glPixelStorei(GL_PACK_SKIP_PIXELS, 0); 


// Get the current read buffer setting and save it. Switch to 

// the front buffer and do the read operation. Finally, restore 

// the read buffer state 

glGetIntegerv(GL_READ_ BUFFER, &lastBuffer) ; 

glReadBuf fer (GL_FRONT) ; 

glReadPixels(®@, ®, iViewport[2], iViewport[3], GL_BGR, 
GL_UNSIGNED_BYTE, pBits); 

glReadBuffer(lastBuffer) ; 


// Initialize the Targa header 
tgaHeader.identsize = 0; 
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LISTING 7.4 Continued 


tgaHeader.colorMapType = 0; 
tgaHeader.imageType = 2; 
tgaHeader.colorMapStart = 0; 
tgaHeader.colorMapLength = 0; 
tgaHeader.colorMapBits = 0; 
tgaHeader.xstart = 0; 
tgaHeader.ystart = 0; 
tgaHeader.width = iViewport[2]; 
tgaHeader.height = iViewport[3]; 
tgaHeader.bits = 24; 
tgaHeader.descriptor = 0; 


// Do byte swap for big vs little endian 
#ifdef — APPLE __ 
BYTE_SWAP(tgaHeader.colorMapStart) ; 
BYTE_SWAP (tgaHeader.colorMapLength) ; 
BYTE_SWAP(tgaHeader.xstart) ; 
BYTE_SWAP(tgaHeader.ystart) ; 
BYTE_SWAP (tgaHeader.width) ; 
BYTE_SWAP(tgaHeader. height) ; 
#endif 


// Attempt to open the file 

pFile = fopen(szFileName, “wb"); 

if(pFile == NULL) 
{ 
free(pBits); // Free buffer and return error 
return Q; 


} 


// Write the header 
fwrite(&tgaHeader, sizeof(TGAHEADER), 1, pFile); 


// Write the image data 
fwrite(pBits, lImageSize, 1, pFile); 


// Free temporary buffer and close the file 
free(pBits) ; 
fclose(pFile) ; 
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LISTING 7.4 Continued 


// Success! 
return 1; 


5 


More Fun with Pixels 


In this section, we discuss OpenGL’s support for magnifying and reducing images, flipping 
images, and performing some special operations during the transfer of pixel data to and 
from the color buffer. Rather than have a different sample program for every special effect 
discussed, we have provided one sample program named OPERATIONS. This sample 
program ordinarily displays a simple color image loaded from a targa file. A right mouse 
click is attached to the GLUT menu system, allowing you to select from one of eight 
drawing modes or to save the modified image to a disk file named screenshot. tga. Listing 
7.5 provides the program in its entirety. We dissect this program and explain it piece by 
piece in the coming sections. 


LISTING 7.5 Source Code for the OPERATIONS Sample Program 


// Operations.c 

// OpenGL SuperBible 

// Demonstrates Imaging Operations 
// Program by Richard S. Wright Jr. 


#include "../../Common/OpenGLSB.h" // System and OpenGL Stuff 
#include "../../Common/GLTools.h" // OpenGL toolkit 
#include <math.h> 


TULTTTTTLTT TTT TTT TT TTL 
// Module globals to save source image data 

static GLubyte *pImage = NULL; 

static GLint iWidth, iHeight, iComponents; 

static GLenum eFormat; 


// Global variable to store desired drawing mode 
static GLint iRenderMode = 1; 


FLLTLTTTTTT TTT TTT TTT TT TT TTT 
// This function does any needed initialization on the rendering 
// context. 

void SetupRC(void) 
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LISTING 7.5 Continued 


{ 
// Black background 
glClearColor(0.0f, 0.0f, 0.0f, 0.0f); 


// Load the horse image 
glPixelStorei(GL_UNPACK_ALIGNMENT, 1); 
pImage = gltLoadTGA("horse.tga", &iWidth, &iHeight, 
&iComponents, &eFormat) ; 
} 


void ShutdownRC (void) 
{ 
// Free the original image data 
free(pImage) ; 
} 


FLTTTITTT TTT TTT TT TTT A TAA TA A Ad 
// Reset flags as appropriate in response to menu selections 
void ProcessMenu(int value) 
{ 
if(value == Q) 
// Save image 
gltWriteTGA("ScreenShot.tga") ; 
else 
// Change render mode index to match menu entry index 
iRenderMode = value; 


// Trigger Redraw 
glutPostRedisplay(); 
} 


FULTTTTTTT TTT TTT TTT A 
// Called to draw scene 
void RenderScene(void) 

{ 

GLint iViewport[4]; 

GLbyte *pModifiedBytes = NULL; 

GLfloat invertMap[ 256]; 

GLint i; 
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LISTING 7.5 Continued 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Current Raster Position always at bottom left hand corner 
glRasterPos2i(@, 0); 


// Do image operation, depending on rendermode index 


switch(iRenderMode) 
{ 
case 2: // Flip the pixels 


glPixelZoom(-1.0f, -1.0f); 
glRasterPos2i(iWidth, iHeight) ; 
break; 


case 3: // Zoom pixels to fill window 
glGetIntegerv(GL_VIEWPORT, iViewport) ; 
glPixelZoom((GLfloat) iViewport[2] / (GLfloat)iWidth, 
(GLfloat) iViewport[3] / (GLfloat)iHeight) ; 
break; 


case 4: // Just Red 
glPixelTransferf(GL_RED_ SCALE, 1.0f); 
glPixelTransferf(GL_GREEN_SCALE, 0.0f); 
glPixelTransferf(GL_BLUE_SCALE, 0.0f); 
break; 


case 5: // Just Green 
glPixelTransferf(GL_RED_SCALE, 0.0f); 
glPixelTransferf (GL_GREEN_SCALE, 1.0f); 
glPixelTransferf(GL_BLUE_SCALE, 0.0f); 
break; 


case 6: // Just Blue 
glPixelTransferf(GL_RED_SCALE, 0.0f); 
glPixelTransferf(GL_GREEN_SCALE, 0.0f); 
glPixelTransferf(GL_BLUE_SCALE, 1.0f); 
break; 


case 7: // Black & White, more tricky 

// First draw image into color buffer 

glDrawPixels(iWidth, iHeight, eFormat, 
GL_UNSIGNED_BYTE, pImage) ; 


More Fun with Pixels 323 


LISTING 7.5 Continued 


// Allocate space for the luminance map 
pModifiedBytes = (GLbyte *)malloc(iWidth * iHeight); 


// Scale colors according to NSTC standard 
glPixelTransferf(GL_RED_SCALE, 0.3f); 
glPixelTransferf (GL_GREEN_SCALE, 0.59f); 
glPixelTransferf(GL_BLUE_SCALE, 0.11f); 


// Read pixels into buffer (scale above will be applied) 
glReadPixels(@,0,iWidth, iHeight, GL_LUMINANCE, 
GL_UNSIGNED_BYTE, pModifiedBytes) ; 


// Return color scaling to normal 
glPixelTransferf(GL_RED_SCALE, 1.0f); 
glPixelTransferf(GL_GREEN_SCALE, 1.0f); 
glPixelTransferf(GL_BLUE_SCALE, 1.0f); 
break; 


case 8: // Invert colors 
invertMap[@] = 1.0f; 
for(i = 1; i < 256; i++) 
invertMap[i] = 1.0f - (1.0f / 255.0f * (GLfloat)i); 


glPixelMapfv(GL_PIXEL_MAP_R_TO_R, 255, invertMap); 
glPixelMapfv(GL_PIXEL_MAP_G_TO_G, 255, invertMap) ; 
glPixelMapfv(GL_PIXEL_MAP_B T0_B, 255, invertMap); 
glPixelTransferi(GL_MAP_COLOR, GL_TRUE); 


break; 
case 1: // Just do a plain old image copy 
default: 
// This line intentionally left blank 
break; 


// Do the pixel draw 
if (pModifiedBytes == NULL) 
glDrawPixels(iWidth, iHeight, eFormat, GL_UNSIGNED_ BYTE, 
piImage) ; 
else 


{ 
glDrawPixels(iWidth, iHeight, GL_LUMINANCE, GL_UNSIGNED_BYTE, 
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pModifiedBytes) ; 

free(pModifiedBytes) ; 

} 
// Reset everything to default 
glPixelTransferi(GL_MAP_COLOR, GL_FALSE) ; 
glPixelTransferf(GL_RED_SCALE, 1.0f); 
glPixelTransferf(GL_GREEN_SCALE, 1.0f); 
glPixelTransferf(GL_BLUE_SCALE, 1.0f); 
glPixelZoom(1.0f, 1.0f); // No Pixel Zooming 


// Do the buffer Swap 
glutSwapBuffers(); 
} 


void ChangeSize(int w, int h) 
{ 
// Prevent a divide by zero, when window is too short 
// (you can't make a window of zero width). 
if(h == Q) 


glViewport(0, @, w, h); 


// Reset the coordinate system before modifying 
glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 


// Set the clipping volume 
gluOrtho2D(0.0f, (GLfloat) w, @.®, (GLfloat) h); 


glMatrixMode(GL_MODELVIEW) ; 
glLoadIdentity(); 
} 


FLTTTLTT TTT TTT TTT TTT TTT TT 
// Main program entrypoint 
int main(int argc, char* argv[]) 

{ 

glutInit(&argc, argv); 
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glutInitDisplayMode(GLUT_RGB | GL_DOUBLE); 
glutInitWindowSize(800@ ,600); 
glutCreateWindow("OpenGL Image Operations") ; 
glutReshapeFunc(ChangeSize) ; 
glutDisplayFunc(RenderScene) ; 


// Create the Menu and add choices 
glutCreateMenu(ProcessMenu) ; 
glutAddMenuEntry("Save Image" ,®Q) ; 
glutAddMenuEntry ("DrawPixels",1); 
glutAddMenuEntry("FlipPixels",2) ; 
glutAddMenuEntry("ZoomPixels",3) ; 
glutAddMenuEntry("“Just Red Channel",4); 
glutAddMenuEntry("“Just Green Channel" ,5); 
glutAddMenuEntry("“Just Blue Channel",6); 
glutAddMenuEntry("Black and White", 7); 
glutAddMenuEntry(“Invert Colors", 8); 
glutAttachMenu(GLUT_RIGHT_BUTTON) ; 


SetupRC(); // Do setup 
glutMainLoop(); // Main program loop 
ShutdownRC() ; // Do shutdown 
return 0; 

} 


The basic framework of this program is simple. Unlike the previous example, IMAGE- 
LOAD, here the image is loaded and kept in memory for the duration of the program so 
that reloading the image is not necessary every time the screen must be redrawn. The 
information about the image and a pointer to the bytes are kept as module global vari- 
ables, as shown here: 


static GLubyte *pImage = NULL; 
static GLint iWidth, iHeight, iComponents; 
static GLenum eFormat; 


The SetupRC function then does little other than load the image and initialize the global 
variables containing the image format, width, and height: 


// Load the horse image 
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glPixelStorei(GL_UNPACK_ALIGNMENT, 1); 
pImage = gltLoadTGA("horse.tga", &iWidth, &iHeight, 
&iComponents, &eFormat) ; 


When the program terminates, you make sure to free the memory allocated by the 
gltLoadTGA function in ShutdownRC: 


free(pImage) ; 


In the main function, you create a menu and add entries and values for the different oper- 
ations you want to accomplish: 


// Create the Menu and add choices 
glutCreateMenu(ProcessMenu) ; 
glutAddMenuEntry("“Save Image" ,®); 
glutAddMenuEntry("Draw Pixels",1); 
glutAddMenuEntry("Flip Pixels" ,2); 
glutAddMenuEntry("Zoom Pixels",3) ; 
glutAddMenuEntry("Just Red Channel" ,4); 
glutAddMenuEntry("“Just Green Channel",5); 
glutAddMenuEntry(“Just Blue Channel" ,6); 
glutAddMenuEntry("“Black and White", 7); 
glutAddMenuEntry("Invert Colors", 8); 
glutAttachMenu(GLUT_RIGHT_BUTTON) ; 


These menu selections then set the variable iRenderMode to the desired value or, if the 
value is 0, save the image as it is currently displayed: 


void ProcessMenu(int value) 

{ 

if (value == 0) 
// Save image 
gltWriteTGA("ScreenShot.tga") ; 

else 
// Change render mode index to match menu entry index 
iRenderMode = value; 


// Trigger Redraw 
glutPostRedisplay() ; 
} 


Finally, the image is actually drawn into the color buffer in the RenderScene function. This 
function contains a switch statement that uses the iRenderMode variable to select from one 
of eight different drawing modes. The default case is simply to perform an unaltered 
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glDrawPixels function, placing the image in the lower-left corner of the window, as 
shown in Figure 7.6. The other cases, however, are now the subject of our discussion. 


{=VOpencl mage Operations 


FIGURE 7.6 The default output of the OPERATIONS sample program. 


Pixel Zoom 


Another simple yet common operation that you may want to perform on pixel data is 
stretching or shrinking the image. OpenGL calls this pixel zoom and provides a function 
that performs this operation: 


void glPixelZoom(GLfloat xfactor, GLfloat yfactor) ; 


The two arguments, xfactor and yfactor, specify the amount of zoom to occur in the x 
and y directions. Zoom can shrink, expand, or even reverse an image. For example, a 
zoom factor of 2 causes the image to be written at twice its size along the axis specified, 
whereas a factor of 0.5 shrinks it by half. As an example, the menu selection Zoom Pixels 
in the OPERATIONS sample program sets the render mode to 3. The following code lines 
are then executed before the call to g1DrawPixels, causing the x and y zoom factors to 
stretch the image to fill the entire window: 


case 3: // Zoom pixels to fill window 
glGetIntegerv(GL_VIEWPORT, iViewport) ; 
glPixelZoom((GLfloat) iViewport[2] / (GLfloat)iWidth, 
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(GLfloat) iViewport[3] / (GLfloat)iHeight) ; 
break; 


The output is shown in Figure 7.7. 


FIGURE 7.7 Using pixel zoom to stretch an image to match the window size. 


A negative zoom factor, on the other hand, has the effect of flipping the image along the 
direction of the zoom. Using such a zoom factor not only reverses the order of the pixels 
in the image, but it also reverses the direction onscreen that the pixels are drawn with 
respect to the raster position. For example, normally an image is drawn with the lower-left 
corner being placed at the current raster position. If both zoom factors are negative, the 
raster position becomes the upper-right corner of the resulting image. 


In the OPERATIONS sample program, selecting Flip Pixels inverts the image both horizon- 
tally and vertically. As shown in the following code snippet, the pixel zoom factors are 
both set to -1.0, and the raster position is changed from the lower-left corner of the 
window to a position that represents the upper-right corner of the image to be drawn (the 
image’s width and height): 


case 2: // Flip the pixels 
glPixelZoom(-1.0f, -1.0f); 
glRasterPos2i(iWidth, iHeight) ; 
break; 


Figure 7.8 shows the inverted image when this option is selected. 
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FIGURE 7.8 Image displayed with x and y dimensions inverted. 


Pixel Transfer 

In addition to zooming pixels, OpenGL supports a set of simple mathematical operations 

that can be performed on image data as it is transferred either to or from the color buffer. 

These pixel transfer modes are set with one of the following functions and the pixel trans- > 
fer parameters listed in Table 7.4: 


void glPixelTransferi(GLenum pname, GLint param); 
void glPixelTransferf(GLenum pname, GLfloat param) ; 


TABLE 7.4 Pixel Transfer Parameters 


Constant oe Type: _ ee Default Value = 
GL_MAP_COLOR GLboolean GL_FALSE 
GL_MAP_STENCIL GLboolean GL_FALSE 
GL_RED_SCALE GLfloat 1.0 

GL_GREEN_SCALE GLfloat 1.0 

GL_BLUE_SCALE GLfloat 1.0 

GL_ALPHA_SCALE GLfloat 1.0 

GL_DEPTH_SCALE GLfloat 1.0 

GL_RED_BIAS GLfloat 0.0 


GL_GREEN_BIAS GLfloat 0.0 
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TABLE 7.4 Continued 


Constant Type Default Value 
GL_BLUE_BIAS GLfloat 0.0 
GL_ALPHA_BIAS GLfloat 0.0 
GL_DEPTH_BIAS GLfloat 0.0 
GL_POST_CONVOLUTION_RED_SCALE GLfloat 1.0 
GL_POST_CONVOLUTION_GREEN_SCALE GLfloat 1.0 
GL_POST_CONVOLUTION_BLUE_SCALE GLfloat 1.0 
GL_POST_CONVOLUTION_ALPHA_SCALE GLfloat 1.0 
GL_POST_CONVOLUTION_RED_BIAS GLfloat 0.0 
GL_POST_CONVOLUTION_GREEN_BIAS GLfloat 0.0 
GL_POST_CONVOLUTION_BLUE_BIAS GLfloat 0.0 
GL_POST_CONVOLUTION_ALPHA_BIAS GLfloat 0.0 
GL_POST_COLOR_MATRIX_RED_SCALE GLfloat 1.0 
GL_POST_COLOR_MATRIX_GREEN_SCALE GLfloat 1.0 
GL_POST_COLOR_MATRIX_BLUE_SCALE GLfloat 1.0 
GL_POST_COLOR_MATRIX_ALPHA_SCALE GLfloat 1.0 
GL_POST_COLOR_MATRIX_RED_BIAS GLfloat 0.0 
GL_POST_COLOR_MATRIX_GREEN_BIAS GLfloat 0.0 
GL_POST_COLOR_MATRIX_BLUE_BIAS GLfloat 0.0 
GL_POST_COLOR_MATRIX_ALPHA_BIAS GLfloat 0.0 


The scale and bias parameters allow you to scale and bias individual color channels. A 
scaling factor is multiplied by the component value, and a bias value is added to that 
component value. A scale and bias operation is common in computer graphics for adjust- 
ing color channel values. The equation is simple: 


New Value = (Old Value * Scale Value) + Bias Value 


By default, the scale values are 1.0, and the bias values are 0.0. They essentially have no 
effect on the component values. Say you want to display a color image’s red component 
values only. To do this, you set the blue and green scale factors to 0.0 before drawing and 
back to 1.0 afterward: 


glPixelTransferf(GL_GREEN_SCALE, 0.0f); 
glPixelTransfer(GL_BLUE_SCALE, 0.0f); 


The OPERATIONS sample program includes the menu selections Just Red, Just Green, and 
Just Blue, which demonstrate this particular example. Each selection turns off all but one 
color channel to show the image’s red, green, or blue color values only: 


case 4: // Just Red 
glPixelTransferf(GL_RED SCALE, 1.0f); 
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glPixelTransferf(GL_GREEN_SCALE, 0.0f); 
glPixelTransferf(GL_BLUE_SCALE, 0.0f); 
break; 


case 5: // Just Green 
glPixelTransferf(GL_RED_SCALE, 0.0f); 
glPixelTransferf(GL_GREEN SCALE, 1.0f); 
glPixelTransferf(GL_BLUE_SCALE, 0.0f); 
break; 


case 6: // Just Blue 
glPixelTransferf(GL_RED_SCALE, 0.0f); 
glPixelTransferf(GL_GREEN_SCALE, 0.0f); 
glPixelTransferf(GL_BLUE_SCALE, 1.0f); 
break; 


After drawing, the pixel transfer for the color channels resets the scale values to 1.0: 


glPixelTransferf(GL_RED_SCALE, 1.0f); 
glPixelTransferf(GL_GREEN_SCALE, 1.0f); 
glPixelTransferf(GL_BLUE_SCALE, 1.0f); 


The post-convolution and post-color matrix scale and bias parameters perform the same 
operation but wait until after the convolution or color matrix operations have been 
performed. These operations are available in the imaging subset, which is discussed 
shortly. 


A more interesting example of the pixel transfer operations is to display a color image in 
black and white. The OPERATIONS sample does this when you choose the Black and 
White menu selection. First, the full color image is drawn to the color buffer: 


glDrawPixels(iWidth, iHeight, eFormat, GL_UNSIGNED BYTE, pImage); 


Next, a buffer large enough to hold just the luminance values for each pixel is allocated: 
pModifiedBytes = (GLbyte *)malloc(iWidth * iHeight); 

Remember, a luminance image has only one color channel, and here you allocate 1 byte 
(8 bits) per pixel. OpenGL automatically converts the image in the color buffer to lumi- 


nance for use when you call glReadPixels but request the data be in the GL_LUMINANCE 
format: 


glReadPixels(@,0,iWidth, iHeight, GL_LUMINANCE, GL_UNSIGNED_BYTE, pModifiedBytes) ; 
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The luminance image can then be written back into the color buffer, and you would see 
the converted black-and-white image: 


glDrawPixels(iWidth, iHeight, GL_LUMINANCE, GL_UNSIGNED_BYTE, 
pModifiedBytes) ; 


Using this approach sounds like a good plan, and it almost works. The problem is that 
when OpenGL converts a color image to luminance, it simply adds the color channels 
together. If the three color channels add up to a value greater than 1.0, it is simply 
clamped to 1.0. This has the effect of oversaturating many areas of the image. This effect is 
shown in Figure 7.9. 


FIGURE 7.9 Oversaturation due to OpenGL’s default color-to-luminance operation. 


To solve this problem, you must set the pixel transfer mode to scale the color value appro- 
priately when OpenGL does the transfer from color to luminance colorspaces. According 
to the National Television Standards Committee (NTSC) standard, the conversion from 
RGB colorspace to black and white (grayscale) is 


Luminance = (0.3 * Red) + (0.59 * Green) + (0.11 * Blue) 


You can easily set up this conversion in OpenGL by calling these functions just before 
glReadPixels: 
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// Scale colors according to NSTC standard 
glPixelTransferf(GL_RED_SCALE, 0.3f); 
glPixelTransferf(GL_GREEN SCALE, 0.59f); 
glPixelTransferf(GL_BLUE_SCALE, 0.11f); 


After reading pixels, you return the pixel transfer mode to normal: 


// Return color scaling to normal 
glPixelTransferf(GL_RED_ SCALE, 1.0f); 
glPixelTransferf(GL_GREEN SCALE, 1.0f); 
glPixelTransferf (GL_BLUE_SCALE, 1.0f); 


The output is now a nice grayscale representation of the image. Because the figures in this 
book are not in color, but grayscale, the output onscreen looks exactly like the image in 
Figure 7.6. 


Pixel Mapping 

In addition to scaling and bias operations, the pixel transfer operation also supports color 
mapping. A color map is a table used as a lookup to convert one color value (used as an 
index into the table) to another color value (the color value stored at that index). Color 
mapping has many applications, such as performing color corrections, making gamma 
adjustments, or converting to and from different color representations. 


You'll notice an interesting example in the OPERATIONS sample program when you select 
Invert Colors. In this case, a color map is set up to flip all the color values during a pixel 
transfer. This means all three channels are mapped from the range 0.0 to 1.0 to the range 
1.0 to 0.0. The result is an image that looks like a photographic negative. 


You enable pixel mapping by calling g1PixelTransfer with the GL_MAP_COLOR parameter 
set to GL_TRUE: 


glPixelTransferi(GL_MAP_COLOR, GL_TRUE) ; 
To set up a pixel map, you must call another function, g1PixelMap, and supply the map in 
one of three formats: 


glPixelMapuiv(GLenum map, GLint mapsize, GLuint *values) ; 
glPixelMapusv(GLenum map, GLint mapsize, GLushort *values) ; 
glPixelMapfv(GLenum map, GLint mapsize, GLfloat *values) ; 


The valid map values are listed in Table 7.5. 
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TABLE 7.5 Pixelmap Parameters 
Map Name 


GL_PIXEL_MAP_R_TO_R 
GL_PIXEL_MAP_G _TO_G 
GL_PIXEL_MAP_B_TO_B 
GL_PIXEL_MAP_A_TO_A 


For the example, you set up a map of 256 floating-point values and fill the map with 
intermediate values from 1.0 to 0.0: 


GLfloat invertMap[256] ; 


invertMap[0] = 1.0f; 
for(i = 1; i < 256; i++) 
invertMap[i] = 1.0f - (1.0f / 255.0f * (GLfloat)i); 


Then you set the red, green, and blue maps to this inversion map and turn on color 
mapping: 

glPixelMapfv(GL_PIXEL_MAP_R_TO_R, 255, invertMap) ; 
glPixelMapfv(GL_PIXEL_MAP_G_TO_G, 255, invertMap) ; 
glPixelMapfv(GL_PIXEL_MAP_B_TO_B, 255, invertMap) ; 
glPixelTransferi(GL_MAP_COLOR, GL_TRUE) ; 


When glDrawPixels is called, the color components are remapped using the inversion 
table, essentially creating a color negative image. Figure 7.10 shows the output. 
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FIGURE 7.10 Using a color map to create a color negative image. 
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All the OpenGL functions covered so far in this chapter for image manipulation have been 
a part of the core OpenGL API since version 1.0. The only exception is the glWindowPos 
function, which was added in OpenGL 1.4 to make it easier to set the raster position. 
These features provide OpenGL with adequate support for most image manipulation 
needs. For more advanced imaging operations, OpenGL may also include, as of version 
1.2, an imaging subset. The imaging subset is optional, which means vendors may choose 
not to include this functionality in their implementation. However, if the imaging subset 
is supported, it is an all-or-nothing commitment to support the entire functionality of 
these features. 


Your application can determine at runtime whether the imaging subset is supported by 
searching the extension string for the token "GL_ARB_imaging". For example, when you 
use the g1Tools library, your code might look something like this: 


if (gltIsExtSupported("GL_ARB_imaging") == 0) 
{ 


// Error, imaging not supported 
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} 
else 


{ 
// Do some imaging stuff 


} 


You access the imaging subset through the OpenGL extension mechanism, which means 
you will likely need to use the glext.h header file and obtain function pointers for the 
functions you need to use. Some OpenGL implementations, depending on your platform’s 
development tools, may already have these functions and constants included in the gl.h 
OpenGL header file (for example, in the Apple XCode headers, they are already defined). 
For compiles on the Macintosh, we use the built-in support for the imaging subset; for the 
PC, we use the extension mechanism to obtain function pointers to the imaging 
functions. 


The IMAGING sample program is modeled much like the previous OPERATIONS sample 
program in that a single sample program demonstrates different operations via the context 
menu. When the program starts, it checks for the availability of the imaging subset and 
aborts if it is not found: 


// Check for imaging subset, must be done after window 
// is create or there won't be an OpenGL context to query 
if (gltIsExtSupported("GL_ARB_imaging") == 0) 

{ 

printf ("Imaging subset not supported\r\n") ; 

return Q; 


} 


The entire RenderScene function is presented in Listing 7.6. We discuss the various pieces 
of this function throughout this section. 


LISTING 7.6 The RenderScene Function from the Sample Program IMAGING 


TTTTTTTT TTT TTT TAT TTA TTT TL 
// Called to draw scene 
void RenderScene(void) 


{ 

GLint i; // Looping variable 

GLint iViewport[4]; // Viewport 

GLint iLargest; // Largest histogram value 


static GLubyte invertTable[256][3];// Inverted color table 
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// Do a black and white scaling 

static GLfloat lumMat[16] = { 0.30f, 0.30f, 0.30f, 0.0f, 
@.59f, 0.59f, 0.59f, 0.0f, 
O.11f, O.11f, O.11f, 0.0f, 
Q.0f, O.0f, O.0f, 1.0f }; 


static GLfloat mSharpen[3][3] = { // Sharpen convolution kernel 
{0.0f, -1.0f, 0.O0f}, 
{-1.0f, 5.0f, -1.0f }, 
{0.0f, -1.0f, O.OfF }}; 


static GLfloat mEmboss[3][3] = { // Emboss convolution kernel 
{ 2.0f, 0.0f, 0.0f }, 
{ 0.0f, -1.0f, 0.0f }, 
{ O.0f, 0.0f, -1.0f }}; 


static GLint histoGram[256]; // Storage for histogram statistics 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Current Raster Position always at bottom left hand corner of window 
glRasterPos2i(@, 0); 
glGetIntegerv(GL_VIEWPORT, iViewport) ; 
glPixelZoom((GLfloat) iViewport[2] / (GLfloat)iWidth, 
(GLfloat) iViewport[3] / (GLfloat)iHeight) ; 


if(bHistogram == GL_TRUE) // Collect Histogram data 
{ 
// We are collecting luminance data, use our conversion formula 
// instead of OpenGL's (which just adds color components together) 
glMatrixMode(GL_COLOR) ; 
glLoadMatrixf (lumMat) ; 
glMatrixMode(GL_MODELVIEW) ; 


// Start collecting histogram data, 256 luminance values 
glHistogram(GL_HISTOGRAM, 256, GL_LUMINANCE, GL_FALSE) ; 
glEnable(GL_HISTOGRAW) ; 

} 
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// Do image operation, depending on rendermode index 


switch(iRenderMode) 
{ 
case 5: // Sharpen image 


glConvolutionFilter2D(GL_CONVOLUTION 2D, GL_RGB, 3, 3, 
GL_LUMINANCE, GL_FLOAT, mSharpen) ; 

glEnable(GL_CONVOLUTION_2D) ; 

break; 


case 4: // Emboss image 
glConvolutionFilter2D(GL_CONVOLUTION_2D, GL_RGB, 3, 3, 
GL_LUMINANCE, GL_FLOAT, mEmboss) ; 
glEnable(GL_CONVOLUTION_2D) ; 
glMatrixMode(GL_COLOR) ; 
glLoadMatrixf (lumMat) ; 
glMatrixMode (GL_MODELVIEW) ; 
break; 


case 3: // Invert Image 
for(i = 0; i < 255; it+) 

{ 
invertTable[i][] 
invertTable[i][1] 
invertTable[i] [2] 

} 


(GLubyte)(255 - i); 
(GLubyte)(255 - i); 
(GLubyte) (255 - i); 


glColorTable(GL_COLOR_TABLE, GL_RGB, 256, GL_RGB, 
GL_UNSIGNED_BYTE, invertTable) ; 

glEnable(GL_COLOR_TABLE) ; 

break; 


case 2: // Brighten Image 
glMatrixMode(GL_COLOR) ; 
glScalef(1.25f, 1.25f, 1.25f); 
glMatrixMode (GL_MODELVIEW) ; 
break; 


case 1: // Just do a plain old image copy 
default: 
// This line intentionally left blank 
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break; 


// Do the pixel draw 
glDrawPixels(iWidth, iHeight, eFormat, GL_UNSIGNED_BYTE, pImage); 


// Fetch and draw histogram? 
if(bHistogram == GL_TRUE) 


{ 
// Read histogram data into buffer 


glGetHistogram(GL_HISTOGRAM, GL_TRUE, GL_LUMINANCE, GL_INT, histoGram) ; 


// Find largest value for scaling graph down 
iLargest = 0; 
for(i = @; i < 255; i++) 
if(iLargest < histoGram[i]) 
iLargest = histoGram[i]; 


// White lines 
glColor3f(1.0f, 1.0f, 1.0f); 
glBegin(GL_LINE_STRIP) ; 
for(i =-@: i < 255; i++) 
glVertex2f((GLfloat)i, 
(GLfloat)histoGram[i] / (GLfloat) iLargest * 128.0f); 
glEnd(); 


bHistogram = GL_FALSE; 
glDisable(GL_HISTOGRAM) ; 
} 


// Reset everyting to default 
glMatrixMode(GL_COLOR) ; 
glLoadIdentity(); 
glMatrixMode(GL_MODELVIEW) ; 
glDisable(GL_CONVOLUTION_2D) ; 
glDisable(GL_COLOR_TABLE) ; 


// Show our hard work... 
glutSwapBuffers() ; 


} 
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The image-processing subset can be broken down into three major areas of new function- 
ality: the color matrix and color table, convolutions, and histograms. Bear in mind that 
image processing is a broad and complex topic all by itself and could easily warrant an 
entire book on this subject alone. What follows is an overview of this functionality with 
some simple examples of their use. For a more in-depth discussion on image processing, 
see the list of suggested references in Appendix A, “Further Reading.” 


Imaging Pipeline 

OpenGL imaging operations are processed in a specific order along what is called the 
imaging pipeline. In the same way that geometry is processed by the transformation 
pipeline, image data goes through the imaging operations in a fixed manner. Figure 7.11 
breaks down the imaging pipeline operation by operation. The sections that follow 
describe these operations in more detail. 


Post-color 
matrix 
color lookup 


FIGURE 7.11 The OpenGL imaging pipeline. 


Color Matrix 

The simplest piece of new functionality added with the imaging subset is the color matrix. 
You can think of color values as coordinates in colorspace—RGB being akin to XYZ on the 
color axis of the color cube (described in Chapter 5, “Color, Materials, and Lighting: The 
Basics”). You could think of the alpha color component as the W component of a vector, 
and it would be transformed appropriately by a 4x4 color matrix. The color matrix is a 
matrix stack that works just like the other OpenGL matrix stacks (GL_MODELVIEW, 
GL_PROJECTION, GL_TEXTURE). You can make the color matrix stack the current stack by 
calling glMatrixMode with the argument GL_COLOR: 


glMatrixMode(GL_COLOR) ; 
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All the matrix manipulation routines (glLoadIdentity, glLoadMatrix, and so on) are 
available for the color matrix. The color matrix stack can be pushed and popped as well, 
but implementations are required to support only a color stack two elements deep. 


A menu item named Increase Contrast in the IMAGING sample program sets the render 
mode to 2, which causes the RenderScene function to use the color matrix to set a positive 
scaling factor to the color values, increasing the contrast of the image: 


case 2: // Brighten Image 
glMatrixMode(GL_COLOR) ; 
glScalef(1.25f, 1.25f, 1.25f); 
glMatrixMode (GL_MODELVIEW) ; 
break; 


The effect is subtle yet clearly visible when the change occurs onscreen. After rendering, 
the color matrix is restored to identity: 


// Reset everything to default 
glMatrixMode(GL_COLOR) ; 
glLoadIdentity(); 
glMatrixMode(GL_MODELVIEW) ; 


Color Lookup 

With color tables, you can specify a table of color values used to replace a pixel’s current 
color. This functionality is similar to pixel mapping but has some added flexibility in the 
way the color table is composed and applied. The following function is used to set up a 
color table: 


void glColorTable(GLenum target, GLenum internalFormat, GLsizei width, 
GLenum format, GLenum type, 
const GLvoid *table); 


The target parameter specifies where in the imaging pipeline the color table is to be 
applied. This parameter may be one of the size values listed in Table 7.6. 


TABLE 7.6 The Place to Apply the Color Lookup Table 


Target Location 

GL_COLOR_TABLE Applied at the beginning of the imaging pipeline 
GL_POST_CONVOLUTION_COLOR_TABLE Applied after the convolution operation 
GL_POST_COLOR_MATRIX_COLOR_TABLE Applied after the color matrix operation 
GL_PROXY_COLOR_TABLE Verify this color table will fit 
GL_PROXY_POST_CONVOLUTION_COLOR_TABLE Verify this color table will fit 


GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE Verify this color table will fit 
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You use the GL_PROXY prefixed targets to verify that the supplied color table can be loaded 
(will fit into memory). 


The internalFormat parameter specifies the internal OpenGL representation of the color 
table pointed to by table. It can be any of the following symbolic constants: GL_ALPHA, 
GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_LUMINANCE, GL_LUMINANCE4, GL_ 
LUMINANCE8, GL_LUMINANCE12, GL_LUMINANCE16, GL_LUMINANCE_ALPHA, 

GL_LUMINANCE4 ALPHA4, GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8 ALPHA8, 
GL_LUMINANCE12_ALPHA4, GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_ 
INTENSITY, GL_INTENSITY4, GL_INTENSITY8, GL_INTENSTIY12, GL_INTENSITY16, GL_RGB, 
GL_R3_G3_B2, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12, GL_RGB16, GL_RGBA, 
GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12, GL_RGBA16. The color 
component name in this list should be fairly obvious to you by now, and the numerical 
suffix simply represents the bit count of that component’s representation. 


The format and type parameters describe the format of the color table being supplied in 
the table pointer. The values for these parameters all correspond to the same arguments 
used in glDrawPixels, and are listed in Tables 7.2 and 7.3. 


The following example demonstrates a color table in action. It duplicates the color inver- 
sion effect from the OPERATIONS sample program but uses a color table instead of pixel 
mapping. When you choose the Invert Color menu selection, the render mode is set to 3, 
and the following segment of the RenderScene function is executed: 


case 3: // Invert Image 
for(i = 0; i < 255; i++) 


{ 


invertTable[i][®] = 255 - i; 
invertTable[iJ][1] = 255 - i; 
invertTable[i][2] = 255 - i; 


} 


glColorTable(GL_COLOR_TABLE, GL_RGB, 256, GL_RGB, 
GL_UNSIGNED BYTE, invertTable); 
glEnable(GL_COLOR_TABLE) ; 


For a loaded color table to be used, you must also enable the color table with a call to 
glEnable with the GL_COLOR_TABLE parameter. After the pixels are drawn, the color table is 
disabled: 


glDisable(GL_COLOR_TABLE) ; 


The output from this example matches exactly the image from Figure 7.10. 
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Proxies An OpenGL implementation’s support for color tables may be limited by system 
resources. Large color tables, for example, may not be loaded if they require too much 
memory. You can use the proxy color table targets listed in Table 7.6 to determine whether 
a given color table fits into memory and can be used. These targets are used in conjunc- 
tion with glGetColorTableParameter to see whether a color table will fit. The 
glGetColorTableParameter function enables you to query OpenGL about the various 
settings of the color tables; it is discussed in greater detail in the reference section. Here, 
you can use this function to see whether the width of the color table matches the width 
requested with the proxy color table call: 


GLint width; 


glColorTable(GL_PROXY_COLOR_TABLE, GL_RGB, 256, GL_RGB, 

GL_UNSIGNED_BYTE, NULL); 
glGetColorTableParameteriv(GL_PROXY_COLOR_ TABLE, GL_COLOR_TABLE_WIDTH, &width); 
if(width == 0) { 

LARERR OR stax 


Note that you do not need to specify the pointer to the actual color table for a proxy. 


Other Operations Also in common with pixel mapping, the color table can be used to 
apply a scaling factor and a bias to color component values. You do this with the follow- 
ing function: 


void glColorTableParameteriv(GLenum target, GLenum pname, GLint *param); 
void glColorTableParameterfv(GLenum target, GLenum pname, GLfloat *param); 


The glColorTableParameter function’s target parameter can be GL_COLOR_TABLE, 
GL_POST_CONVOLUTION_COLOR_TABLE, or GL_POST_COLOR_MATRIX_COLOR_TABLE. The pname 
parameter sets the scale or bias by using the value GL_COLOR_TABLE_SCALE or 
GL_COLOR_TABLE_BIAS, respectively. The final parameter is a pointer to an array of four 
elements storing the red, green, blue, and alpha scale or bias values to be used. 


You can also actually render a color table by using the contents of the color buffer (after 
some rendering or drawing operation) as the source data for the color table. The function 
glCopyColorTable takes data from the current read buffer (the current GL_READ_BUFFER) as 
its source: 


void glCopyColorTable(GLenum target, GLenum internalFormat, 
GLint x, GLint y, GLsizei width); 


The target and internalFormat parameters are identical to those used in g1ColorTable. 
The color table array is then taken from the color buffer starting at the x,y location and 
taking width pixels. 
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You can replace all or part of a color table by using the g1ColorSubTable function: 


void glColorSubTable(GLenum target, GLsizei start, GLsizei count, 
GLenum format, GLenum type, const void *data); 


Here, most parameters correspond directly to the g1ColorTable function, except for start 
and count. The start parameter is the offset into the color table to begin the replacement, 
and count is the number of color values to replace. 


Finally, you can also replace all or part of a color table from the color buffer in a manner 
similar to gl1CopyColorTable by using the glCopyColorSubTable function: 


void glCopyColorSubTable(GLenum target, GLsizei start, 
GLint x, GLint y, GlLsizei width); 


Again, the source of the color table is the color buffer, with x and y placing the position to 
begin reading color values, start being the location within the color table to begin the 
replacement, and width being the number of color values to replace. 


Convolutions 

Convolutions are a powerful image-processing technique, with many applications such as 
blurring, sharpening, and other special effects. A convolution is a filter that processes 
pixels in an image according to some pattern of weights called a kernel. The convolution 
replaces each pixel with the weighted average value of that pixel and its neighboring 
pixels, with each pixel’s color values being scaled by the weights in the kernel. 


Typically, convolution kernels are rectangular arrays of floating-point values that represent 
the weights of a corresponding arrangement of pixels in the image. For example, the 
following kernel from the IMAGING sample program performs a sharpening operation: 


static GLfloat mSharpen[3][3] = { // Sharpen convolution kernel 
{0.0f, -1.0f, 0.Of}, 
{-1.0F, SeOf, -10f '}; 
{0.O0f, -1.0f, O.OF }}; 


The center pixel value is 5.0, which places a higher emphasis on that pixel value. The 
pixels immediately above, below, and to the right and left have a decreased weight, and 
the corner pixels are not accounted for at all. Figure 7.12 shows a sample block of image 
data with the convolution kernel superimposed. The 5 in the kernel’s center is the pixel 
being replaced, and you can see the kernel’s values as they are applied to the surrounding 
pixels to derive the new center pixel value (represented by the circle). The convolution 
kernel is applied to every pixel in the image, resulting in a sharpened image. You can see 
this process in action by selecting Sharpen Image in the IMAGING sample program. 
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FIGURE 7.12 The sharpening kernel in action. 


To apply the convolution filter, the IMAGING program simply calls these two functions 
before the glDrawPixels operation: 


glConvolutionFilter2D(GL_CONVOLUTION 2D, GL_RGB, 3, 3, 
GL_LUMINANCE, GL_FLOAT, mSharpen) ; 
glEnable(GL_CONVOLUTION_2D) ; 


The glConvolutionFilter2D function has the following syntax: 


void glConvolutionFilter2D(GLenum target, GLenum internalFormat, 
GLsizei width, GLsizei height, GLenum format, 
GLenum type, const GLvoid *image); 


The first parameter, target, must be GL_CONVOLUTION_2D. The second parameter, 
internalFormat, takes the same values as glColorTable and specifies to which pixel 
components the convolution is applied. The width and height parameters are the width 
and height of the convolution kernel. Finally, format and type specify the format and 
type of pixels stored in image. In the case of the sharpening filter, the pixel data is in 
GL_RGB format, and the kernel is GL_LUMINANCE because it contains simply a single weight 
per pixel (as opposed to having a separate weight for each color channel). Convolution 
kernels are turned on and off simply with glEnable or glDisable and the parameter 
GL_CONVOLUTION_2D. 


Convolutions are a part of the imaging pipeline and can be combined with other imaging 
operations. For example, the sharpening filter already demonstrated was used in conjunc- 
tion with pixel zoom to fill the entire window with the image. For a more interesting 
example, let’s combine pixel zoom with the color matrix and a convolution filter. The 
following code excerpt defines a color matrix that will transform the image into a black- 
and-white (grayscale) image and a convolution filter that does embossing: 


// Do a black and white scaling 
static GLfloat lumMat[16] = { 0.30f, 0.30f, 0.30f, 0.0f, 
Q.59f, 0.59f, 0.59f, 0.0f, 
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11f, O.11f, O.11f, 0.0f, 
Q.0f, O.0f, O.0f, 1.0f }; 


static GLfloat mSharpen[3] [3] 
{0.O0f, -1.0f, 0.O0f}, 
{-1.0f, 5.0f, -1.0f }, 
{0.0f, -1.0f, 0.Of }}; 


{ // Sharpen convolution kernel 


static GLfloat mEmboss[3][3] = { // Emboss convolution kernel 
{ 2.0f, 0.0f, 0.Of }, 
{ @.0f, -1.0f, 0.0f }, 
{ 0.0f, 0.O0f, -1.0F }}; 


When you select Emboss Image from the pop-up menu, the render state is changed to 4, 
and the following case from the RenderScene function is executed before g1DrawPixels: 


case 4: // Emboss image 
glConvolutionFilter2D(GL_CONVOLUTION_2D, GL_RGB, 3, 3, 
GL_LUMINANCE, GL_FLOAT, mEmboss) ; 
glEnable(GL_CONVOLUTION_ 2D) ; 
glMatrixMode(GL_COLOR) ; 
glLoadMatrixf (lumMat) ; 
glMatrixMode(GL_MODELVIEW) ; 
break; 


The embossed image is displayed in Figure 7.13. 


From the Color Buffer Convolution kernels can also be loaded from the color buffer. The 
following function behaves similarly to loading a color table from the color buffer: 


void glCopyConvolutionFilter2D(GLenum target, GLenum internalFormat, 
GLint x, GLint y, GLsizei width, GLsizei height); 


The target value must always be GL_CONVOLUTION_2D, and internalFormat refers to the 
format of the color data, as in glConvolutionFilter2D. The kernel is loaded from pixel 
data from the color buffer located at (x,y) and the given width and height. 


Separable Filters A separable convolution filter is one whose kernel can be represented 
by the matrix outer product of two one-dimensional filters. For example, in Figure 7.14, 
one-dimensional row and column matrices are multiplied to yield a final 3x3 matrix (the 
new kernel filter). 
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FIGURE 7.13 Using convolutions and the color matrix for an embossed effect. 
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FIGURE 7.14 The outer product to two one-dimensional filters. 


The following function is used to specify these two one-dimensional filters: 


void glSeparableFilter2D(GLenum target, GLenum internalFormat, 
GLsizei width, GLsizei height, 
GLenum format, GLenum type, 
void *row, const GLvoid *column) ; 


The parameters all have the same meaning as in glConvolutionFilter2D, with the excep- 
tion that now you have two parameters for passing in the address of the filters: row and 
col. The target parameter, however, must be GL_SEPARABLE_2D in this case. 


One-Dimensional Kernels OpenGL also supports one-dimensional convolution filters, but 
they are applied only to one-dimensional texture data. They behave in the same manner 
as two-dimensional convolutions, with the exception that they are applied only to rows of 
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pixels (or actually texels in the case of one-dimensional texture maps). These one-dimen- 
sional convolutions have one-dimensional kernels, and you can use the corresponding 
functions for loading and copying the filters: 


glConvolutionFilter1D(GLenum target, GLenum internalFormat, 
GLsizei width, GLenum format, GLenum type, 
const GLvoid *image) ; 


glCopyConvolutionFilter1D(GLenum target, GLenum internalFormat, 
GLint x, GLint y, GLsizei width); 


Of course, with these functions the target must be set to GL_CONVOLUTION_1D. 


Other Convolution Tweaks When a convolution filter kernel is applied to an image, 
along the edges of the image the kernel will overlap and fall outside the image’s borders. 
How OpenGL handles this situation is controlled via the convolution border mode. You 
set the convolution border mode by using the g1ConvolutionParameter function, which 
has four variations: 


glConvolutionParameteri(GLenum target, GLenum pname, GLint param) ; 
glConvolutionParameterf(GLenum target, GLenum pname, GLfloat param) ; 
glConvolutionParameteriv(GLenum target, GLenum pname, GLint *params) ; 
glConvolutionParameterfv(GLenum target, GLenum pname, GLfloat *params) ; 


The target parameter for these functions can be either GL_CONVOLUTION_1D, GL_ 
CONVOLUTION_2D, or GL_SEPARABLE_2D. To set the border mode, you use 
GL_CONVOLUTION_BORDER_MODE as the pname parameter and one of the border mode 
constants as param. 


If you set param to GL_CONSTANT_BORDER, the pixels outside the image border are computed 
from a constant pixel value. To set this pixel value, call gl1ConvolutionParameterfv with 
GL_CONSTANT_BORDER and a floating-point array containing the RGBA values to be used as 
the constant pixel color. 


If you set the border mode to GL_REDUCE, the convolution kernel is not applied to the edge 
pixels. Thus, the kernel never overlaps the edge of the image. In this case, however, you 
should note that you are essentially shrinking the image by the width and height of the 
convolution filter. 


The final border mode is GL_REPLICATE_BORDER. In this case, the convolution is applied as 
if the horizontal and vertical edges of an image are replicated as many times as necessary 
to prevent overlap. 


You can also apply a scale and bias value to kernel values by using 
GL_CONVOLUTION_FILTER_BIAS and/or GL_CONVOLUTION_FILTER_SCALE for the parameter 
name (pname) and supplying the bias and scale values in param or params. 
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Histogram 

A histogram is a graphical representation of an image’s frequency distribution. In English, 
it is simply a count of how many times each color value is used in an image, displayed as 
a sort of bar graph. Histograms may be collected for an image’s intensity values or sepa- 
rately for each color channel. Histograms are frequently employed in image processing, 
and many digital cameras can display histogram data of captured images. Photographers 
use this information to determine whether the camera captured the full dynamic range of 
the subject or if perhaps the image is too over- or underexposed. Popular image-processing 
packages such as Adobe Photoshop also calculate and display histograms, as shown in 
Figure 7.15. 


FIGURE 7.15 A histogram display in Photoshop. 


When histogram collection is enabled, OpenGL collects statistics about any images as they 
are written to the color buffer. To prepare to collect histogram data, you must tell OpenGL 
how much data to collect and in what format you want the data. You do this with the 
glHistogram function: 


void glHistogram(GLenum target, GLsizei width, 
GLenum internalFormat, GLboolean sink); 


The target parameter must be either GL_HISTOGRAM or GL_PROXY_HISTOGRAM (used to deter- 
mine whether sufficient resources are available to store the histogram). The width parame- 
ter tells OpenGL how many entries to make in the histogram table. This value must be a 
power of 2 (1, 2, 4, 8, 16, and so on). The internalFormat parameter specifies the data 
format you expect the histogram to be stored in, corresponding to the valid format para- 
meters for color tables and convolution filters, with the exception that GL_INTENSITY is 
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not included. Finally, you can discard the pixels and not draw anything by specifying 
GL_TRUE for the sink parameter. You can turn histogram data collection on and off with 
glEnable or glDisable by passing in GL_HISTOGRAM, as in this example: 


glEnable(GL_HISTOGRAM) ; 


After image data has been transferred, you collect the histogram data with the following 
function: 


void glGetHistogram(GLenum target, GLboolean reset, GLenum format, 
GLenum type, GLvoid *values) ; 


The only valid value for target is GL_HISTOGRAM. Setting reset to GL_TRUE clears the 
histogram data. Otherwise, the histogram becomes cumulative, and each pixel transfer 
continues to accumulate statistical data in the histogram. The format parameter specifies 
the data format of the collected histogram information, and type and values are the data 
type to be used and the address where the histogram is to be placed. 


Now, let’s look at an example using a histogram. In the IMAGING sample program, select- 
ing Histogram from the menu displays a grayscale version of the image and a graph in the 
lower-left corner that represents the statistical frequency of each color luminance value. 
The output is shown in Figure 7.16. 


8 OpenGL Imaging 


FIGURE 7.16 A histogram of the luminance values of the image. 
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The first order of business in the RenderScene function is to allocate storage for the 
histogram. The following line creates an array of integers 256 elements long. Each element 
in the array contains a count of the number of times that corresponding luminance value 
was used when the image was drawn onscreen: 


static GLint histoGram[256]; // Storage for histogram statistics 


Next, if the histogram flag is set (through the menu selection), you tell OpenGL to begin 
collecting histogram data. The function call to glHistogram instructs OpenGL to collect 

statistics about the 256 individual luminance values that may be used in the image. The 
sink is set to false so that the image is also drawn onscreen: 


if(bHistogram == GL_TRUE) // Collect Histogram data 
{ 
// We are collecting luminance data, use our conversion formula 
// instead of OpenGL's (which just adds color components together) 
glMatrixMode(GL_COLOR) ; 
glLoadMatrixf (lumMat) ; 
glMatrixMode(GL_MODELVIEW) ; 


// Start collecting histogram data, 256 luminance values 
glHistogram(GL_HISTOGRAM, 256, GL_LUMINANCE, GL_FALSE); 
glEnable(GL_HISTOGRAM) ; 

} 


Note that in this case you also need to set up the color matrix to provide the grayscale 
color conversion. OpenGL’s default conversion to GL_LUMINANCE is simply a summing of 
the red, green, and blue color components. When you use this conversion formula, the 
histogram graph will have the same shape as the one from Photoshop for the same image 
display in Figure 7.15. 


After the pixels are drawn, you collect the histogram data with the code shown here: 


// Fetch and draw histogram? 
if(bHistogram == GL_TRUE) 
{ 
// Read histogram data into buffer 
glGetHistogram(GL_HISTOGRAM, GL_TRUE, GL_LUMINANCE, GL_INT, histoGram) ; 


Now you traverse the histogram data and search for the largest collected value. You do this 
because you will use this value as a scaling factor to fit the graph in the lower-left corner 
of the display: 


// Find largest value for scaling graph down 
GLint iLargest = 0; 
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For (i 03 2. <.2553 itt) 
if(iLargest < histoGram[i]) 
iLargest = histoGram[i]; 


Finally, it’s time to draw the graph of statistics. The following code segment simply sets 
the drawing color to white and then loops through the histogram data creating a single 
line strip. The data is scaled by the largest value so that the graph is 256 pixels wide and 
128 pixels high. When all is done, the histogram flag is reset to false and the histogram 
data collection is disabled with a call to g1Disable: 


// White lines 
glColor3f(1.0f, 1.0f, 1.0f); 
glBegin(GL_LINE_STRIP); 
for(i = 0; i < 255; i++) 
glVertex2f((GLfloat)i, (GLfloat)histoGram[i] / 
(GLfloat) iLargest * 128.0f); 
glEnd(); 


bHistogram = GL_FALSE; 
glDisable(GL_HISTOGRAM) ; 
} 


MinMax Operations In the preceding sample, you traversed the histogram data to find 
the largest luminance component for the rendered image. If you need only the largest or 
smallest components collected, you can choose not to collect the entire histogram for a 
rendered image, but instead collect the largest and smallest values. This minmax data 
collection operates in a similar manner to histograms. First, you specify the format of the 
data on which you want statistics gathered by using the following function: 


void glMinmax(GLenum target, GLenum internalFormat, GLboolean sink); 

Here, target is GL_MINMAX, and internalFormat and sink behave precisely as in 
glHistogram. You must also enable minmax data collection: 

glEnable(GL_MINMAX) ; 

The minmax data is collected with the g1GetMinmax function, which is analogous to 
glGetHistogram: 

void glGetMinmax(GLenum target, GLboolean reset, GLenum format, 


GLenum type, GLvoid *values) ; 


Again, the target parameter is GL_MINMAX, and the other parameters map to their counter- 
parts in glGetHistogram. 


Reference 


Summary 


In this chapter, we have shown that OpenGL provides first-class support for color image 
manipulation—from reading and writing bitmaps and color images directly to the color 
buffer, to color processing operations and color lookup maps. Optionally, many OpenGL 
implementations go even further by supporting the OpenGL imaging subset. The imaging 
subset makes it easy to add sophisticated image-processing filters and analysis to your 
graphics intensive programs. 


We have also laid the groundwork in this chapter for our return to 3D geometry in the 
next chapter, where we begin coverage of OpenGL’s texture mapping capabilities. You'll 
find the functions covered in this chapter that load and process image data are used 
directly when we extend the manipulation of image data by mapping it to 3D primitives. 


Reference 

glBitmap 

Purpose: Draws a bitmap at the current raster position. 
Include File: <gl.h> 

Syntax: 


void glBitmap(GLsizei width, GLsizei height, GLfloat xorig, GLfloat yorig, 
GLfloat xmove, GLfloat ymove, const GLubyte *bitmap) ; 


Description: In OpenGL, bitmaps are binary image patterns without color data. This 
function draws a bitmap pattern at the current raster position. The width 
and height of the bitmap must be specified as well as any offset within 
the binary image map. The current raster position is updated after the 
bitmap is transferred by the amount specified by the xmove and ymove 
parameters. Bitmaps take the color that was current at the time the raster 
position was specified with glRasterPos or glWindowPos. 

Parameters: 

width, height GLsizei: The width and height of the bitmap. 

xorig, yorig GLsizei: The location of the bitmap’s origin measured from the bottom- 
left corner. 

xmove, ymove GLsizei: The offset in the x and y direction added to the current raster 
position after drawing. 

bitmap const GLubyte*: Pointer to the bitmap image. 

Returns: None. 

See Also: glRasterPos, glWindowPos, glDrawPixels, glPixelStore 
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glColorSubTable 
Purpose: Replaces all or part of an existing color table. 


Include File: 
Syntax: 


<gl.h> 


void glColorSubTable(GLenum target, GLsizei start, GLsizei count, 


Description: 


Parameters: 
target 


start 


count 


format 


Returns: 
See Also: 


glColorTable 


GLenum format, GLenum type, const void *data); 


This function allows you to replace all or a portion of an already estab- 
lished color table. Color tables consume system resources, and some 
performance advantage may be gained by replacing all or part of a color 
table rather than respecifying another table of the same size and format. 


GLenum: Color table target. This parameter has the same meaning as when 
used for glColorTable and may be any value in Table 7.6. 


GLsizei: Beginning position within the color table to begin the replace- 
ment. 


GLsizei: The count of color table entries to be replaced. 


GLenum: The format of the color table data. It may be any value used for 
specifying the original table with g1ColorTable. 


None. 
glColorTable, glCopyColorSubTable 


Specifies a table of color lookup replacement values. 


Purpose: 
Include File: 
Syntax: 


<gl.h> 


void glColorTable(Glenum target, GLenum internalFormat, GLsizei width, 


Description: 


GLenum format, GLenum type, const GLvoid *table); 


Color tables are lookup tables used to replace pixel color values. The 
component color values of the pixel are used as the lookup values into 
the table pointed to by table. The color value stored at this location is 
substituted for the original color component value from the pixel being 
processed. The color table operation must be enabled by calling 
glEnable(GL_COLOR_TABLE). 
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Parameters: 
target GLenum: The color table being loaded. It may be any value from Table 7.6. 


internalFormat GLenum: The internal OpenGL representation of the table. It may be any 
of the following symbolic constants: GL_ALPHA, GL_ALPHA4, GL_ALPHA8, 
GL_ALPHA12, GL_ALPHA16, GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8, 
GL_LUMINANCE12, GL_LUMINANCE16, GL_LUMINANCE_ALPHA, 
GL_LUMINANCE4 ALPHA4, GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8_ALPHAS8, 
GL_LUMINANCE12_ALPHA4, GL_LUMINANCE12_ALPHA12, 
GL_LUMINANCE16_ALPHA16, GL_INTENSITY, GL_INTENSITY4, GL_INTENSITY8, 
GL_INTENSTIY12, GL_INTENSITY16, GL_RGB, GL_R3_G3_B2, GL_RGB4, 
GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12, GL_RGB16, GL_RGBA, GL_RGBA2, 
GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB1®_A2, GL_RGBA12, GL_RGBA16 


width GLsizei: The width in pixels of the color table. This value must be a 
power of 2 (1, 2, 4, 8, 16, 32, 64, and so on). 

format GLenum: The format of the pixel data. It may be any of the formats from 
Table 7.2. 

type GLenum: The data type of the pixel components. Any pixel data type from 
Table 7.3 is valid. 

table void*: A pointer to the array comprising the color table. 

Returns: None. 

See Also: glColorSubTable, glColorTableParameter, glCopyColorSubTable, 
glCopyColorTable 


glColorTableParameter 


N 
Purpose: Sets a color table’s scale and bias values. 
Include File: <gl.h> 
Variations: 


void glColorTableParameteriv(GLenum target, GLenum pname, GLint *param) ; 
void glColorTableParameterfv(GLenum target, GLenum pname, GLfloat *param) ; 


Description: This function allows you to apply a scaling and bias factor to color table 
lookup values. Scaling factors are multiplied by the color component 
values, and bias values are added. Color component values are still 
clamped to the range [0,1]. 


Parameters: 


target GLenum: The color table the parameter is to be applied to. It may be 
GL_COLOR_TABLE, GL_POST_CONVOLUTION_COLOR_TABLE, or 
GL_POST_COLOR_MATRIX_COLOR_TABLE. 
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pname GLenum: Either GL_COLOR_TABLE_SCALE to set the scaling factor or 
GL_COLOR_TABLE_BIAS to set the bias factor. 
param GLint* or GLfloat *: A pointer to an array of values for the scale or bias 


factors. The array should have the same number of elements as the 
number of color components in the color table. 


Returns: None. 
See Also: glColorTable 


glConvolutionFilter1D 


Purpose: Specifies a one-dimensional convolution filter. 
Include File: <gl.h> 
Syntax: 


void glConvolutionFilter1D(GLenum target, GLenum internalformat, 
GLsizei width, GLenum format, GLenum type, 
const GLvoid *image) ; 


Description: This function sets a one-dimensional convolution filter that will be used 
with glTexImage1D. One-dimensional convolution filters have no effect 
on 2D imaging operations. You must enable this operation by calling 
glEnable(GL_CONVOLUTION_1D). 

Parameters: 

target GLenum: The target of the filter. It must be GL_CONVOLUTION_1D. 


internalformat GLenum: The pixel components the filter is to be applied to. Any of the 
formats listed in Table 7.3 may be specified. 


width GLsizei: The width of the filter. 

format GLenum: The color format of the filter data. Any format from Table 7.2 
may be used. 

type GLenum: The data type for the filter image values. Any of the data types 
from Table 7.3 may be used. 

image GLvoid *: A pointer to the filter image data. 

Returns: None. 

See Also: glConvolutionFilter2D 


glConvolutionFilter2D 


Purpose: Specifies a two-dimensional convolution filter. 
Include File: <gl.h> 


Reference 


Syntax: 


void glConvolutionFilter2D(GLenum target, GLenum internalformat, 
GLsizei width, GLsizei height, GLenum format, 
GLenum type, const GLvoid *image); 


Description: This function sets a two-dimensional convolution filter to be used with 
glCopyPixels, gl1DrawPixels, glReadPixels, and glTexImage2D. You 
must enable this operation by calling glEnable(GL_CONVOLUTION 2D). 

Parameters: 

target GLenum: The target of the filter. It must be GL_CONVOLUTION_2D. 


internalformat GLenum: The pixel components the filter is to be applied to. Any of the 
formats listed in Table 7.2 may be specified. 


width GLsizei: The width of the filter. 

height GLsizei: The height of the filter. 

format GLenum: The color format of the filter data. Any format from Table 7.3 
may be used. 

type GLenum: The data type for the filter image values. Any of the data types 
from Table 7.3 may be used. 

image GLvoid *: A pointer to the filter image data. 

Returns: None. 

See Also: glConvolutionFilter1D 


glConvolutionParameter 


Purpose: Sets convolution operating parameters. 
Include File: <gl.h> 
Syntax: 


glConvolutionParameteri(GLenum target, GLenum pname, GLint param); 
glConvolutionParameterf(GLenum target, GLenum pname, GLfloat param); 
glConvolutionParameteriv(GLenum target, GLenum pname, GLint *params) ; 
glConvolutionParameterfv(GLenum target, GLenum pname, GLfloat *params) ; 


Description: This function sets parameters that affect the operation of the target 
convolution filter. 


Parameters: 

target GLenum: The convolution filter whose parameter is to be set. It must be 
GL_CONVOLUTION_1D, GL_CONVOLUTION_2D, or GL_SEPARABLE_2D. 

pname GLenum: The convolution parameter to retrieve. It must be one of 


GL_CONVOLUTION_BORDER_COLOR, GL_CONVOLUTION_BORDER_MODE, GL_ 
CONVOLUTION_FILTER_SCALE, or GL_CONVOLUTION_FILTER_BIAS. 
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param GLint or GLfloat: The value of the parameter to be set. 

params GLint* or GLfloat*: A pointer to storage that contains the parameter 
values to be set. 

Returns: None. 

See Also: g1GetConvolutionParameter 

glCopyColorSubTable 

Purpose: Replaces a portion of a color table with data from the color buffer. 


Include File: <gl.h> 
Syntax: 


void glCopyColorSubTable(GLenum target, GLsizei start, 
GLint x, GLint y, GLsizei width); 


Description: This function replaces a color table’s entries using values read from the 
color buffer. 

Parameters: 

target GLenum: The color table to operate on. It may be GL_COLOR_TABLE, 
GL_POST_CONVOLUTION_COLOR_TABLE, or 
GL_POST_COLOR_MATRIX_COLOR_TABLE. 

start GLsizei: Offset into the color table to begin the replacement. 

XY GLsizei: The x and y location in the color buffer to begin the data 
extraction. 

width GLsizei: The number of color table entries to replace. 

Returns: None. 

See Also: glColorTable, glColorSubTable, glCopyColorTable 

glCopyColorTable 

Purpose: Creates a new color table using data from the color buffer. 

Include File: <gl.h> 

Syntax: 


void glCopyColorTable(GLenum target, GLenum internalFormat, 
GLint x, GLint y, GLsizei width); 


Description: This function creates a new color table in the fashion of glColorTable. 
However, this function reads the color table values from the color buffer 
instead of from a user-specified data buffer. 


Reference 


Parameters: 

target GLenum: The color table to operate on. It may be GL_COLOR_TABLE, 
GL_POST_CONVOLUTION_COLOR_TABLE, or 
GL_POST_COLOR_MATRIX_COLOR_TABLE. 


internalFormat GLenum: The internal OpenGL format of the color data. It may be any of 
the same set of values used for g1ColorTable listed in Table 7.2. 


x,y GLint: The location in the color buffer to begin reading the color table 
values. 

width GLsizei: The number of color entries to load. 

Returns: None. 

See Also: glColorTable, glCopyColorSubTable 


glCopyConvolutionFilter1D 


Purpose: Defines a one-dimensional convolution filter from the color buffer. 
Include File: <gl.h> 
Syntax: 


void glCopyConvolutionFilter1D(GLenum target, GLenum internalFormat, 
GLint x, GLint y, Glsizei width); 


Description: This function loads a one-dimensional convolution filter using data read 
from the color buffer. 

Parameters: 

target GLenum: The target of the filter. It must be GL_CONVOLUTION_1D. 


internalformat GLenum: The pixel components the filter is to be applied to. Any of the 
formats listed in Table 7.2 may be specified. 

x,y GLint: The x and y location in the color buffer that specifies the begin- 
ning of the data source for the convolution filter. 


width GLsizei: The width of the convolution filter in pixels. 
Returns: None. 
See Also: glConvolutionFilter1D, glCopyConvolutionFilter2D 


glCopyConvolutionFilter2D 


Purpose: Defines a two-dimensional convolution filter from the color buffer. 
Include File: <gl.h> 
Syntax: 


void glCopyConvolutionFilter2D(GLenum target, GLenum internalFormat, 
GLint x, GLint y, GLsizei width, GLsizei height) ; 
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Description: 


Parameters: 
target 
internal format 


x,y 


width 
height 
Returns: 
See Also: 


glCopyPixels 


Purpose: 
Include File: 
Syntax: 


This function loads a two-dimensional convolution filter using data read 
from the color buffer. 


GLenum: The target of the filter. It must be GL_CONVOLUTION_2D. 


GLenum: The pixel components the filter is to be applied to. Any of the 
formats listed in Table 7.2 may be specified. 


GLint: The x and y location in the color buffer that specifies the begin- 
ning of the data source for the convolution filter. 


GLsizei: The width of the convolution filter in pixels. 
GLsizei: The height of the convolution filter in pixels. 
None. 

glConvolutionFilter2D, glCopyConvolutionFilter1D 


Copies a block of pixels in the framebuffer. 
<gl.h> 


void glCopyPixels(GLint x, GLint y, GLsizei width, 


Description: 


Parameters: 


height 


type 


GLsizei height, GLenum type); 


This function copies pixel data from the indicated area in the framebuffer 
to the current raster position. You use glRasterPos or glWindowPos to set 
the current raster position. If the current raster position is not valid, no 
pixel data is copied. Calls to glDrawBuffer, glPixelMap, 
glPixelTransfer, glPixelZoom, glReadBuffer, and the imaging subset 
affect the operation of glCopyPixels. 


GLint: The lower-left corner window horizontal coordinate. 

GLint: The lower-left corner window vertical coordinate. 

GLsizei: The width of the image in pixels. If negative, the image is 
drawn from right to left. By default, images are drawn from left to right. 
GLsizei: The height of the image in pixels. If negative, the image is 
drawn from top to bottom. By default, images are drawn bottom to top. 
GLenum: The source of the pixel values to be copied. Any of the pixel 
types from Table 7.7 may be used. 
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TABLE 7.7 Pixel Value Types 


Type Description 
GL_COLOR Color buffer values 
GL_STENCIL Stencil buffer values 
GL_DEPTH Depth buffer values 
Returns: None. 
See Also: glDrawBuffer, glPixelMap, glPixelStore, glPixelTransfer, 
glPixelZoom, glReadBuffer 
glDrawPixels 
Purpose: Draws a block of pixels into the framebuffer. 


Include File: 
Syntax: 


<gl.h> 


void glDrawPixels(GLsizei width, GLsizei height, GLenum format, 


Description: 


Parameters: 
width 
height 


format 


type 


pixels 
Returns: 
See Also: 


GLenum type, const void *pixels); 


This function copies pixel data from memory to the current raster posi- 
tion. You use glRasterPos or glWindowPos to set the current raster posi- 
tion. If the current raster position is not valid, no pixel data is copied. 
Besides the format and type arguments, several other parameters define 
the encoding of pixel data in memory and control the processing of pixel 
data before it is placed in the color buffer. 


GLsizei: The width of the image in pixels. 


GLsizei: The height of the image in pixels. If negative, the image is 
drawn from top to bottom. By default, images are drawn from bottom to 
top. 

GLenum: The colorspace of the pixels to be drawn. Any value from Table 
7.2 may be used. 


GLenum: The data type of the color components. Valid data types are listed 
in Table 7.3. 


void *: A pointer to the pixel data for the image. 
None. 
glDrawBuffer, glPixelMap, g1PixelStore, glPixelTransfer, gl1PixelZoom 
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glGetConvolutionFilter 


Purpose: Retrieves the current convolution filter. 
Include File: <gl.h> 
Syntax: 


void glGetConvolutionFilter(GLenum target, GLenum format, 
GLenum type, void *data); 


Description: This function allows you to query and read back the current convolution 
filter. You must allocate sufficient space in *data to store the convolution 
filter kernel. 


Parameters: 

target GLenum: The convolution filter to retrieve. It must be either GL_ 
CONVOLUTION_1D or GL_CONVOLUTION_2D. 

format GLenum: The desired pixel format of convolution data. It may be any of 
the pixel formats from Table 7.2 with the exception of GL_STENCIL_INDEX 
and GL_DEPTH_COMPONENT. 

type GLenum: The data type of the data storage. It may be any of the data types 
from Table 7.3. 

data void *: A pointer to the buffer to receive the convolution filter data. 

Returns: None. 

See Also: glConvolutionFilter1D, glConvolutionFilteraD, 


glGetConvolutionParameter 


glGetConvolutionParameter 


Purpose: Queries for the various convolution parameters. 
Include File: <gl.h> 
Variations: 


void glGetConvolutionParameteriv(GLenum target, GLenum pname, GLint* params); 
void glGetConvolutionParameterfv(GLenum target, GLenum pname, GLfloat* params); 


Description: This function allows you to query OpenGL for the current state of all the 
convolution parameters in effect. 

Parameters: 

target GLenum: The convolution filter to retrieve. It must be GL_CONVOLUTION_1D, 


GL_CONVOLUTION_2D, or GL_SEPARABLE_2D. 
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Description: 


Imaging with OpenGL 


This function allows you to query the values of any of the color table 
parameter settings. The results can be read back as either integers or float- 
ing-point values. 


Parameters: 

target GLenum: One of the color table names listed in Table 7.6. 

pname GLenum: One of the following color table parameters: 
GL_COLOR_TABLE_SCALE, GL_COLOR_TABLE_BIAS, GL_COLOR_TABLE_FORMAT, 
GL_COLOR_TABLE_WIDTH, GL_COLOR_TABLE_RED_SIZE, 
GL_COLOR_TABLE_GREEN_SIZE, GL_COLOR_TABLE_BLUE_SIZE, 
GL_COLOR_TABLE_ALPHA_SIZE, GL_COLOR_TABLE_LUMINANCE_SIZE, 
GL_COLOR_TABLE_INTENSITY_SIZE. 

params GLint* or GLfloat*: The address of the variable to receive the retrieved 
parameter value. 

Returns: None. 

See Also: glColorTableParameter 

glGetHistogram 

Purpose: Returns collected histogram statistics. 

Include File: <gl.h> 

Syntax: 


void glGetHistogram(GLenum target, GLboolean reset, GLenum format, 


Description: 


Parameters: 
target 
reset 


format 


type 


values 


GLenum type, GLvoid *values) ; 


This function retrieves the histogram data that was collected after a previ- 
ous call to glHistogram. You must also enable histogram collection by 
enabling GL_HISTOGRAM. 


GLenum: The histogram target to retrieve. It must be GL_HISTOGRAM. 


GLboolean: A flag to indicate whether the histogram statistics should be 
cleared after they are copied to values. 

GLenum: The storage format of the color counts. Any of the values from 
Table 7.2 may be used. 

GLenum: The data type of the storage for the color counts. Any of the 
values from Table 7.3 may be used. 

void*: A pointer to the buffer to receive the histogram statistics. 


Sufficient space must be allocated ahead of time to store the histogram 
data. 
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Returns: None. 
See Also: glHistogram, glResetHistogram 


glGetHistogramParameter 


Purpose: Retrieves information about the current histogram parameters. 
Include File: <gl.h> 
Variations: 


void glGetHistogramParameteriv(GLenum target, GLenum pname, GLint* params); 
void glGetHistogramParameterfv(GLenum target, GLenum pname, GLfloat* params); 


Description: These functions retrieve information about the way the current 
histogram is set up. The parameter GL_HISTOGRAM_SINK cannot be used 
with GL_PROXY_HISTOGRAM. Histogram proxies are used to determine 
whether a specific histogram can be used with the current system 


resources. 

Parameters: 

target GLenum: The histogram target about which to retrieve information. It 
must be GL_HISTOGRAM or GL_PROXY_HISTOGRAM. 

pname GLenum: The parameter to retrieve. It may be one of the following: 
GL_HISTOGRAM_FORMAT, GL_HISTOGRAM_WIDTH, GL_HISTOGRAM_RED_ SIZE, 
GL_HISTOGRAM_GREEN_SIZE, GL_HISTOGRAM_BLUE_SIZE, 
GL_HISTOGRAM_ALPHA_SIZE, GL_HISTOGRAM_LUMINANCE_SIZE, 
GL_HISTOGRAM_SINK. 

params GLint* or GLfloat*: The address of the variable to receive the queried NJ 
parameter. 

Returns: None. 

See Also: glHistogram, glGetHistogram 

glGetMinmax 

Purpose: Gets the minimum and maximum color values. 

Include File: <gl.h> 

Syntax: 


void glGetMinmax(GLenum target, GLboolean reset, GLenum format, 
GLenum type, GLvoid *values) ; 


Description: This function gets the minimum and maximum color values that have 
been used. 
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Parameters: 


target 
reset 


format 
type 
values 
Returns: 
See Also: 


Imaging with OpenGL 


GLenum: The min/max buffer target. It must be GL_MINMAX. 


GLboolean: A value of GL_TRUE resets the minimum and maximum buffer 
values. 


GLenum: The format of the values array, taken from Table 7.2. 
GLenum: The type of values in the array, taken from Table 7.3. 
GLvoid *: A pointer to the values array. 

None. 

glMinMax, glResetMinMax 


glGetSeparableFilter 


Purpose: 


Include File: 


Syntax: 


Retrieves the contents of the current separable filter. 
<gl.h> 


void glGetSeparableFilter(GLenum target, GLenum format, GLenum type, 


Description: 


Parameters: 


target 
format 


type 


row, column 


span 


Returns: 
See Also: 


glHistogram 


Purpose: 


Include File: 


Syntax: 


void *row, void *column, const GLvoid *span); 


This function allows you to retrieve the size and contents of the current 
separable convolution filter. 


GLenum: The separable filter to retrieve. It must be GL_SEPARABLE_2D. 


GLenum: The desired format of the values. It may be any of the pixel 
values from Table 7.2. 


GLenum: The data type of the data storage. It may be any of the data types 
from Table 7.3. 


void *: Destination buffers for the row and column separable convolu- 
tion filters. 


void*: An unused parameter reserved for future use. 
None. 
glSeparableFilter2D 


Defines how histogram statistics should be stored. 
<gl.h> 


void glHistogram(GLenum target, GLsizei width, 


GLenum internalFormat, GLboolean sink); 
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Description: This function defines how OpenGL should collect and store histogram 
data. If target is set to GL_PROXY_HISTOGRAM, the 
glGetHistogramParameter function can be used to see whether sufficient 
system resources are available to honor the request. 


Parameters: 

target GLenum: The histogram target. It must be either GL_HISTOGRAM or 
GL_PROXY_HISTOGRAM. 

width GLsizei: The number of entries in the histogram table. This value must 


be a power of 2. 


internalFormat GLenum: The way histogram data should be stored. Allowable values are 
GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_LUMINANCE, 
GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12, GL_LUMINANCE16, 
GL_LUMINANCE_ALPHA, GL_LUMINANCE4 ALPHA4, GL_LUMINANCE6_ALPHA2, 
GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4, 
GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_RGB, 
GL_R3_G3_B2, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB1, GL_RGB12, GL_RGB16, 
GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, 
GL_RGBA12, GL_RGBA16. 


sink GLboolean: Flag to determine whether pixels continue in the imaging 

pipeline. 
Returns: None. 
See Also: glGetHistogram, glResetHistogram 
glMinmax 

N 

Purpose: Initializes the min/max buffer. 
Include File: <gl.h> 
Syntax: 


void glMinmax(GLenum target, GLenum internalFormat, GLboolean sink); 


Description: This function initializes the min/max buffer. 
Parameters: 
target GLenum: This value must be GL_MINMAX. 


internalFormat GLenum: The internal format of the values array. It may be any of the 
formats used by glHistogram. 


sink GLboolean: Flag to determine whether pixels are passed down the 
imaging pipeline. 

Returns: None. 

See Also: glGetMinMax, glResetMinMax 
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glPixelMap 

Purpose: Defines a lookup table for pixel transfers. 
Include File: <gl.h> 

Variations: 


void glPixelMapfv(GLenum map, GLint mapsize, const GLfloat *values); 
void glPixelMapuiv(GLenum map, GLint mapsize, const GLuint *values); 
void glPixelMapusv(GLenum map, GLint mapsize, const GLushort *values) ; 


Description: This function sets lookup tables for gl1CopyPixels, glDrawPixel, 
glReadPixels, glTexImage1D, and glTexImage2D. These lookup tables, or 
maps, are used only if the corresponding GL_MAP_COLOR or 
GL_MAP_STENCIL option is enabled with g1PixelTransfer. Maps are 
applied prior to drawing and after reading values from the framebuffer. 


Parameters: 

map GLenum: The type of map being defined. Valid values are listed in 
Table 7.5. 

mapsize GLint: The size of the lookup table. 

values GLfloat * or GLuint * or GLushort *: The lookup table. 

Returns: None. 

See Also: glCopyPixels, glDrawPixels, glPixelStore, glPixelTransfer, 
glReadPixels, glTexImage1D, glTexImage2D 

g!PixelStore 

Purpose: Controls how pixels are stored or read from memory. 

Include File: <gl.h> 

Variations: 


void glPixelStorei(GLenum pname, GLint param); 
void glPixelStoref(GLenum pname, GLfloat param) ; 


Description: This function controls how pixels are stored with g1ReadPixels and read 
for glDrawPixels, glTexImage1D, and glTexImage2D. It does not affect the 
operation of glCopyPixels. 


Parameters: 
pname GLenum: The parameter to set. It must be one of the values from Table 7.8. 
param GLint or GLfloat: The parameter value. Valid values for the different 


parameters are given in Table 7.8. 
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TABLE 7.8 Pixel Storage Types 


Name Default Description 
GL_PACK_SWAP_BYTES GL_TRUE If true, all multibyte values have their bytes swapped 
when stored in memory. 
GL_PACK_LSB_FIRST GL_FALSE If true, bitmaps have their leftmost pixel stored in bit 
0 instead of bit 7. 
GL_PACK_ROW_LENGTH 0 This storage type sets the pixel width of the image. If 
0, the width argument is used instead. 
GL_PACK_SKIP_PIXELS 0 This storage type sets the number of pixels to skip 
horizontally in the image. 
GL_PACK_SKIP_ROWS 0 This storage type sets the number of pixels to skip 
vertically in the image. 
GL_PACK_ALIGNMENT 4 This storage type sets the alignment of each scanline 
in the image. 
GL_UNPACK_SWAP_BYTES GL_TRUE If true, all multibyte values have their bytes swapped 
when read from memory. 
GL_UNPACK_LSB_FIRST GL_FALSE if true, bitmaps have their leftmost pixel read from bit 
0 instead of bit 7. 
GL_UNPACK_ROW_LENGTH 0 This storage type sets the pixel width of the image. If 
0, the width argument is used instead. 
GL_UNPACK_SKIP_PIXELS 0 This storage type sets the number of pixels to skip 
horizontally in the image. 
GL_UNPACK_SKIP_ROWS 0 This storage type sets the number of pixels to skip 
vertically in the image. 
GL_UNPACK_ALIGNMENT 4 This storage type sets the alignment of each scanline 
in the image. 
Returns: None. 
See Also: glDrawPixels, glReadPixels, glTexImage1D, glTexImage2D 
g!PixelTransfer 
Purpose: Sets pixel transfer modes. 
Include File: <gl.h> 
Syntax: 


void glPixelTransferi(GLenum pname, GLint param) ; 
void glPixelTransferf(GLenum pname, GLfloat param) ; 


Description: This function sets pixel transfer modes for gl1CopyPixels, glDrawPixels, 
glReadPixels, glTexImage1D, and glTexImage2D. 
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Parameters: 

pname GLenum: The transfer parameter to set. It may be any value from Table 7.4. 

param GLint or GLfloat: The parameter value. 

Returns: None. 

See Also: glCopyPixels, glDrawPixels, glPixelMap, glReadPixels, glTexImage1D, 
glTexImage2D 

glPixelZoom 

Purpose: Sets the scaling for pixel transfers. 


Include File: 
Syntax: 


<gl.h> 


void glPixelZoom(GLfloat xfactor, GLfloat yfactor) 


Description: 


Parameters: 
xfactor 
yfactor 
Returns: 
See Also: 


glRasterPos 


Purpose: 
Include File: 
Variations: 


This function sets pixel scaling for g1CopyPixels, glDrawPixels, 
glReadPixels, glTexImage1D, and glTexImage2D. Pixels are scaled using 
the nearest neighbor algorithm when they are read from memory or the 
framebuffer. In the case of glCopyPixels and glDrawPixels, the scaled 
pixels are drawn in the framebuffer at the current raster position. 


GLfloat: The horizontal scaling factor (1.0 is no scaling). 

GLfloat: The vertical scaling factor (1.0 is no scaling). 

None. 

glCopyPixels, glDrawPixels, glReadPixels, glTexImage1D, glTexImage2D 


Sets the current raster position. 
<gl.h> 


void glRasterPos2d(GLdouble x, GLdouble y); 
void glRasterPos2dv(GLdouble *v); 

void glRasterPos2f(GLfloat x, GLfloat y); 
void glRasterPos2fv(Glfloat *v); 

void glRasterPos2i(GLint x, GLint y); 

void glRasterPos2iv(Glint *v); 

void glRasterPos2s(GLshort x, GLshort y); 
void glRasterPos2sv(GLshort *v); 


void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
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glRasterPos3d(GLdouble x, GLdouble y, Gldouble z); 
glRasterPos3dv(GLdouble *v); 

glRasterPos3f(GLfloat x, GLfloat y, GLfloat z); 
glRasterPos3fv(GLfloat *v); 

glRasterPos3i(GLint x, GLint y, GLint z); 
glRasterPos3iv(GLint *v); 

glRasterPos3s(GLshort x, GLshort y, GLshort z); 
glRasterPos3sv(GLshort *v); 

glRasterPos4d(GLdouble x, GLdouble y, GLdouble z, GLdouble w); 
glRasterPos4dv(GLdouble *v); 

glRasterPos4f(GLfloat x, GLfloat y, GLfloat z, GLfloat w); 
glRasterPos4fv(GLfloat *v); 

glRasterPos4i(GLint x, GLint y, GLint z, GLint w); 
glRasterPos4iv(Glint *v); 

glRasterPos4s(GLshort x, GLshort y, GlLshort z, GLshort w); 
glRasterPos4sv(GLshort *v); 


Description: This function sets the current raster position. The coordinates supplied 


are transformed and projected by the current modelview and projection 
matrix, resulting in a 2D window position. If the raster position is outside 
the window boundaries, it is invalid, and no raster operations will occur. 
The current color for bitmaps (g1Bitmap) is taken from the current color 
when the raster position is set. 


Parameters: 

xX, Y, Z,W GLdouble or GLfloat or GLint or GLshort: The x, y, z, and w coordinates 
of the raster position. 

v GLdouble* or GLfloat* or GLint* or GLshort*: A pointer to an array 
containing the coordinates of the raster position. 

Returns: None. 

See Also: glWindowPos 

glReadPixels 

Purpose: Reads a block of pixels from the framebuffer. 

Include File: <gl.h> 

Syntax: 

void glReadPixels(GLint x, GLint y, GLsizei width, GLsizei height, 


GLenum format, GLenum type, const void *pixels); 
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Description: This function copies pixel data from the framebuffer to memory. Besides 
the format and type arguments, several other parameters define the 
encoding of pixel data in memory and control the processing of pixel 
data before it is placed in the memory buffer. Pixel values are modified 
according to the settings of the current pixel map, pixel storage mode, 
pixel transfer operation, and current read buffer. 

Parameters: 

x GLint: The lower-left corner window horizontal coordinate. 

y GLint: The lower-left corner window vertical coordinate. 

width GLsizei: The width of the image in pixels. 

height GLsizei: The height of the image in pixels. 

format GLenum: The colorspace of the pixels to be read. It may be taken from the 
constants defined in Table 7.2. 

type GLenum: The desired data type for the returned pixels. This may be any of 
the values listed in Table 7.3. 

pixels void *: A pointer to the pixel data for the image. 

Returns: None. 

See Also: glPixelMap, glPixelStore, glPixelTransfer, glReadBuffer 

glResetHistogram 

Purpose: Clears the histogram buffer. 


Include File: 
Syntax: 


<gl.h> 


void glResetHistogram(GLenum target) ; 


Description: This function clears the histogram buffer. 

Parameters: 

target GLenum: The histogram target. It must be GL_HISTOGRAM. 
Returns: None. 

See Also: glGetHistogram, glHistogram 

glResetMinmax 

Purpose: Resets the min/max color values. 


Include File: 


Syntax: 


<gl.h> 


void glResetMinMax(GLenum target) ; 


Reference 


Description: This function resets the min/max color values. 
Parameters: 

target GLenum: The min/max target. It must be GL_MINMAX. 
Returns: None. 

See Also: glGetMinMax, glMinMax 

glSeparableFilter2D 

Purpose: Defines a two-dimensional separable convolution filter. 
Include File: <gl.h> 

Syntax: 


void glSeparableFilter2D(GLenum target, GLenum internalFormat, 
GLsizei width, GLsizei height, 
GLenum format, GLenum type, 
void *row, const GLvoid *column) ; 


Description: This function specifies a two-dimensional separable convolution filter. 
This filter is specified with two one-dimensional arrays. The final two- 
dimensional convolution filter is derived from the outer product of these 
two arrays. 

Parameters: 

target GLenum: The separable filter target. It must be GL_SEPARABLE_2D. 


internalformat GLenum: The pixel components the filter is to be applied to. Any of the 
formats listed in Table 7.2 may be specified. 


width GLsizei: The width of the filter. 

height GLsizei: The height of the filter. 

format GLenum: The color format of the filter data. Any format from Table 7.3 
may be used. 

type GLenum: The data type for the filter image values. Any of the data types 
from Table 7.3 may be used. 

row void *: The row array data. 

column void *: The column array data. 

Returns: None. 


See Also: glGetSeparableFilter 
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glWindowPos 

Purpose: Sets the raster position in window coordinates. 
Include File: <gl.h> 

Variations: 

void glWindowPos2d(GLdouble x, GLdouble y); 


void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 


glWindowPos2dv(GLdouble *v); 
glWinodwPos2f(GLfloat x, GLfloat y); 
glWindowPos2fv(Glfloat *v); 

glWindowPos2i(GLint x, GLint y); 
glWindowPos2iv(Glint *v); 

glWindowPos2s(GLshort x, GLshort y); 
glWindowPos2sv(GLshort *v); 
glWindowPos3d(GLdouble x, GLdouble y, GLdouble z); 
glWindowPos3dv(GLdouble *v); 
glWindowPos3f(GLfloat x, GLfloat y, GLfloat z); 
glWindowPos3fv(GLfloat *v); 

glWindowPos3i(GLint x, GLint y, GLint z); 
glWindowPos3iv(GLint *v); 

glWindowPos3s(GLshort x, GLshort y, GLshort z); 


void glWindowPos3sv(GLshort *v); 

Description: This function sets the current raster position in window coordinates. If 
the specified position falls outside the window, the raster position is 
invalid, and no raster operations are performed. Unlike g1lRasterPos, this 
function does not transform the coordinates by the transformation matri- 
ces, but allows specification of the raster position directly in window 
coordinates. 

Parameters: 

Xie Viz GLdouble or GLfloat or GLint or GLshort: The x, y, and z coordinates of 
the raster position in window coordinates. 

Vv GLdouble* or GLfloat* or GLint* or GLshort*: A pointer to an array 
containing the coordinates of the raster position. 

Returns: None. 


See Also: glRasterPos 


CHAPTER 8 


Texture Mapping: The Basics 


by Richard S. Wright, Jr. 


WHAT YOU’LL LEARN IN THIS CHAPTER 


How To Functions You'll Use 
Load texture images glTexImage, glTexSubImage 
Map textures to geometry glTexCoord 


Change the texture environment glTexEnv 

Set texture mapping parameters glTexParameter 
Generate mipmaps gluBuildMipmaps 
Manage multiple textures glBindTexture 


In the preceding chapter, we covered in detail the groundwork for loading image data into 
OpenGL. Image data, unless modified by pixel zoom, generally has a one-to-one corre- 
spondence between a pixel in an image to a pixel on the screen. In fact, this is where we 
get the term pixel (picture element). In this chapter, we extend this knowledge further by 
applying images to three-dimensional primitives. When we apply image data to a geomet- 
ric primitive, we call this a texture or texture map. Figure 8.1 shows the dramatic difference 
that can be achieved by texture mapping geometry. The cube on the left is a lit and 
shaded featureless surface, whereas the cube on the right shows a richness in detail that 
can be reasonably achieved only with texture mapping. 


A texture image when loaded has the same makeup and arrangement as pixmaps, but now 
a one-to-one correspondence seldom exists between texels (the individual picture elements 
in a texture) and pixels on the screen. This chapter covers the basics of loading a texture 
map into memory and all the ways in which it may be mapped to and applied to geomet- 
ric primitives. 
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FIGURE 8.1 The stark contrast between textured and untextured geometry. 


Loading Textures 


The first necessary step in applying a texture map to geometry is to load the texture into 
memory. Once loaded, the texture becomes part of the current texture state (more on this 
later). Three OpenGL functions are most often used to load texture data from a memory 
buffer (which is, for example, read from a disk file): 


void glTexImage1D(GLenum target, GLint level, GLint internalformat, 
GLsizei width, GLint border, 
GLenum format, GLenum type, void *data); 


void glTexImage2D(GLenum target, GLint level, GLint internalformat, 
GLsizei width, GLsizei height, GLint border, 
GLenum format, GLenum type, void *data); 


void glTexImage3D(GLenum target, GLint level, GLint internalformat, 
GLsizei width, GLsizei height, GLsizei depth, GLint border, 
GLenum format, GLenum type, void *data); 


These three rather lengthy functions tell OpenGL everything it needs to know about how 
to interpret the texture data pointed to by the data parameter. 


The first thing you should notice about these functions is that they are essentially three 
flavors of the same root function, g1TexImage. OpenGL supports one-, two-, and three- 
dimensional texture maps and uses the corresponding function to load that texture and 
make it current. You should also be aware that OpenGL copies the texture information 
from data when you call one of these functions. This data copy can be quite expensive, 
and in the section “Texture Objects” we discuss some ways to help mitigate this problem. 


Loading Textures 


The target argument for these functions should be GL_TEXTURE_1D, GL_TEXTURE_2D, or 
GL_TEXTURE_3D, respectively. You may also specify proxy textures in the same manner that 
you used proxies in the preceding chapter by specifying GL_PROXY_TEXTURE_1D, 
GL_PROXY_TEXTURE_2D, or GL_PROXY_TEXTURE_3D and using the function 
glGetTexParameter to retrieve the results of the proxy query. 


The level parameter specifies the mipmap level being loaded. Mipmaps are covered in an 
upcoming section called “Mipmapping”, so for non-mipmapped textures (just your plain 
old ordinary texture mapping), always set this to 0 (zero) for the moment. 


Next, you have to specify the internalformat parameter of the texture data. This informa- 
tion tells OpenGL how many color components you want stored per texel and possibly 
the storage size of the components and/or whether you want the texture compressed (see 
the next chapter for information about texture compression). Table 8.1 lists the most 
common values for this function. A complete listing is given in the reference section. 


TABLE 8.1 Most Common Texture Internal Formats 


Constant Meaning 

GL_ALPHA Store the texels as alpha values 

GL_LUMINANCE Store the texels as luminance values 

GL_LUMINANCE_ALPHA Store the texels with both luminance and alpha values 
GL_RGB Store the texels as red, green, and blue components 
GL_RGBA Store the texels as red, green, blue, and alpha components 


The width, height, and depth parameters (where appropriate) specify the dimensions of 
the texture being loaded. It is important to note that these dimensions must be integer 
powers of 2 (1, 2, 4, 8, 16, 32, 64, and so on). There is no requirement that texture maps 
be square (all dimensions equal), but a texture loaded with a nonpower of 2 dimensions 
will cause texturing to be implicitly disabled. 


The border parameter allows you to specify a border width for texture maps. Texture 
borders allow you to extend the width, height, or depth of a texture map by an extra set 
of texels along the borders. Texture borders play an important role in the discussion of 
texture filtering to come. For the time being, always set this value to 0 (zero). 


The last three parameters—format, type, and data—are identical to the corresponding 
arguments when you used g1DrawPixels to place image data into the color buffer. For 
the sake of convenience, we listed the valid constants for format and type in Tables 8.2 
and 8.3. 
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TABLE 8.2 Texel Formats for glTexImage 


Constant Description 

GL_RGB Colors are in red, green, blue order. 

GL_RGBA Colors are in red, green, blue, alpha order. 
GL_BGR/GL_BGR_EXT Colors are in blue, green, red order. 

GL_BGRA/GL_BGRA_EXT Colors are in blue, green, red, alpha order. 

GL_RED Each pixel contains a single red component. 

GL_GREEN Each pixel contains a single green component. 

GL_BLUE Each pixel contains a single blue component. 

GL_ALPHA Each pixel contains a single alpha component. 

GL_LUMINANCE Each pixel contains a single luminance (intensity) component. 
GL_LUMINANCE_ALPHA Each pixel contains a luminance followed by an alpha component. 
GL_STENCIL_INDEX Each pixel contains a single stencil index. 
GL_DEPTH_COMPONENT Each pixel contains a single depth component. 


TABLE 8.3 Data Types for Pixel Data 


Constant Description 

GL_UNSIGNED_BYTE Each color component is an 8-bit unsigned integer 
GL_BYTE Signed 8-bit integer 

GL_BITMAP Single bits, no color data; same as g1Bitmap 
GL_UNSIGNED_SHORT Unsigned 16-bit integer 

GL_SHORT Signed 16-bit integer 

GL_UNSIGNED_INT Unsigned 32-bit integer 

GL_INT Signed 32-bit integer 

GL_FLOAT Single precision float 

GL_UNSIGNED_BYTE_3 2 2 Packed RGB values 

GL_UNSIGNED_BYTE_2_3 3 REV Packed RGB values 
GL_UNSIGNED_SHORT_5_6_5 Packed RGB values 
GL_UNSIGNED_SHORT_5_6_5_REV Packed RGB values 

GL_UNSIGNED_SHORT_4_4 4 4 Packed RGBA values 
GL_UNSIGNED_SHORT_4_4 4 4 REV Packed RGBA values 
GL_UNSIGNED_SHORT_5_5 5 1 Packed RGBA values 
GL_UNSIGNED_SHORT_1_5_5_5_REV Packed RGBA values 

GL_UNSIGNED_INT_8_8 8 8 Packed RGBA values 

GL_UNSIGNED_INT_8_8 8 8 REV Packed RGBA values 
GL_UNSIGNED_INT_10_10_10 2 Packed RGBA values 


GL_UNSIGNED_INT_2 1010.10 REV Packed RGBA values 


Loaded textures are not applied to geometry unless the appropriate texture state is 
enabled. You can call glEnable or glDisable with GL_TEXTURE_1D, GL_TEXTURE_2D, or 
GL_TEXTURE_3D to turn texturing on or off for a given texture state. Only one of these 
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texture states may be on at a time for a given texture unit (see the next chapter for a 
discussion of multitexturing). However, it is good practice to turn unused texture states off 
when not in use. For example, to switch between one-dimensional and two-dimensional 
texturing, you would call 


glDisable(GL_TEXTURE_1D); 
glEnable(GL_TEXTURE_2D) ; 


A final word about texture loading: Texture data loaded by the g1TexImage functions goes 
through the same pixel and imaging pipeline covered in the preceding chapter. This 
means pixel packing, pixelzoom, color tables, convolutions, and so on are applied to the 
texture data when it is loaded. 


Using the Color Buffer 

One- and two-dimensional textures may also be loaded using data from the color buffer. 
You can read an image from the color buffer and use it as a new texture by using the 
following two functions: 


void glCopyTexImage1D(GLenum target, GLint level, GLenum internalformat, 
GLint x, GLint y, 
GLsizei width, GLint border); 


void glCopyTexImage2D(GLenum target, GLint level, GLenum internalformat, 
GLint x, GLint y, 
GLsizei width, GLsizei height, GLint border); 


These functions operate similarly to g1TexImage, but in this case, x and y specify the loca- 
tion in the color buffer to begin reading the texture data. The source buffer is set using 
glReadBuffer and behaves just like glReadPixels. 


Updating Textures 

Repeatedly loading new textures can become a performance bottleneck in time-sensitive 
applications such as games or simulation applications. If a loaded texture map is no longer 
needed, it may be replaced entirely or in part. Replacing a texture map can often be done 
much quicker than reloading a new texture directly with glTexImage. The function you 
use to accomplish this is g1TexSubImage, again in three variations: 


void glTexSubImage1D(GLenum target, GLint level, 
GLint x0ffset, 
GLsizei width, 
GLenum format, GLenum type, const GLvoid *data) ; 
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void glTexSubImage2D(GLenum target, GLint level, 
GLint xOffset, GLint yOffset, 
GLsizei width, GLsizei height, 
GLenum format, GLenum type, const GLvoid *data); 


void glTexSubImage3D(GLenum target, GLint level, 
GLint xOffset, GLint yOffset, GLint zOffset, 
GLsizei width, GLsizei height, GLsizei depth, 
GLenum format, GLenum type, const GLvoid *data); 


Most of the arguments correspond exactly to the parameters used in g1TexImage. The 
xOffset, yOffset, and zOffset parameters specify the offsets into the existing texture map 
to begin replacing texture data. The width, height, and depth values specify the dimen- 
sions of the texture being “inserted” into the existing texture. 


A final set of functions allows you to combine reading from the color buffer and inserting 
or replacing part of a texture. These glCopyTexSubImage variations do just that: 


void glCopyTexSubImage1D(GLenum target, GLint level, 
GLint xoffset, 
GLint x, GLint y, 
GLsizei width) ; 


void glCopyTexSubImage2D(GLenum target, GLint level, 
GLint xoffset, GLint yoffset, 
GLint x, GLint y, 
GLsizei width, GLsizei height); 


void glCopyTexSubImage3D(GLenum target, GLint level, 
GLint xoffset, GLint yoffset, Glint zoffset, 
GLint x, GLint y, 
GLsizei width, GLsizei height); 


You may have noticed that no glCopyTexImage3D function is listed here. The reason is that 
the color buffer is 2D, and there simply is no corresponding way to use a 2D color image 
as a source for a 3D texture. However, you can use glCopyTexSubImage3bD to use the color 
buffer data to set a plane of texels in a three-dimensional texture. 


Mapping Textures to Geometry 


Loading a texture and enabling texturing cause OpenGL to apply the texture to any of the 
OpenGL primitives. You must, however, provide OpenGL with information about how to 
map the texture to the geometry. You do this by specifying a texture coordinate for each 
vertex. Texels in a texture map are addressed not as a memory location (as you would for 
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pixmaps), but as a more abstract (usually floating-point values) texture coordinate. 
Typically, texture coordinates are specified as floating-point values that are clamped in the 
range 0.0 to 1.0. Texture coordinates are named s, t, r, and q (similar to vertex coordinates 
x, y, z, and w) supporting from one- to three-dimensional texture coordinates, and option- 
ally a way to scale the coordinates. 


Figure 8.2 shows one-, two-, and three-dimensional textures and the way the texture coor- 
dinates are laid out with respect to their texels. 


(0.0) (0.5) (1.0) 


Texture s coordinate 


One dimensional 
texture coordinate 


(0,0,0) (1,0,0) 


Texture s coordinate 
FIGURE 8.2 How texture coordinates address texels. 


Because there are no four-dimensional textures, you might ask what the q coordinate is 
for. The g coordinate corresponds to the w geometric coordinate. This is a scaling factor 
applied to the other texture coordinates; that is, the actual values used for the texture 
coordinates are s/q, t/q, and r/q. By default, q is set to 1.0. 


You specify a texture coordinate using the glTexCoord function. Much like vertex coordi- 
nates, surface normals, and color values, this function comes in a variety of familiar 
flavors that are all listed in the reference section. The following are three simple variations 
used in the sample programs: 


void glTexCoordif(GLfloat s); 
void glTexCoord2f(Glfloat s, GLfloat t); 
void glTexCoord3f(GLfloat s, GLfloat t, GLfloat r); 


One texture coordinate is applied using these functions for each vertex. OpenGL then 
stretches or shrinks the texture as necessary to apply the texture to the geometry as 
mapped. (This stretching or shrinking is applied using the current texture filter; we discuss 
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this issue shortly as well.) Figure 8.3 shows an example of a two-dimensional texture being 
mapped to a GL_QUAD. Note the corners of the texture correspond to the corners of the 
quad. As you do with other vertex properties (materials, normals, and so on), you must 
specify the texture coordinate before the vertex! 


(1,1) 


(0,0 (1,0) 


FIGURE 8.3 Applying a two-dimensional texture to a quad. 


Rarely, however, do you have such a nice fit of a square texture mapped to a square piece 
of geometry. To help you better understand texture coordinates, we provide another 
example in Figure 8.4. This figure also shows a square texture map, but the geometry is a 
triangle. Superimposed on the texture map are the texture coordinates of the locations in 
the map being extended to the vertices of the triangle. 


Texture Matrix 


Texture coordinates can also be transformed via the texture matrix. The texture matrix 
stack works just like the other matrices previously discussed (modelview, projection, and 
color). You make the texture matrix the target of matrix function calls by calling 
glMatrixMode with the argument GL_TEXTURE: 


glMatrixMode (GL_TEXTURE) ; 
The texture matrix stack is required to be only two elements deep for the purposes of 


glPushMatrix and glPopMatrix. Texture coordinates can be translated, scaled, and even 
rotated. 


A Simple 2D Example 


(0.5,1) 


(0.5,1.0) 


FIGURE 8.4 Applying a portion of a texture map to a triangle. 


A Simple 2D Example 


Loading a texture and providing texture coordinates are the fundamental requirements for 
texture mapping. There are a number of issues we have yet to address, such as coordinate 
wrapping, texture filters, and the texture environment. What do they mean, and how do 
we make use of them? Let’s pause here first and examine a simple example that uses a 2D 
texture. In the code that follows, we use the functions covered so far and add several new 
ones. We use this example, then, as a framework to describe these additional texture 
mapping issues. 


Listing 8.1 shows all the code for the sample program PYRAMID. This program draws a 
simple lit four-sided pyramid made up of triangles. A stone texture is applied to each face 
and the bottom of the pyramid. You can spin the pyramid around with the arrow keys 
much like the samples in earlier chapters. Figure 8.5 shows the output of the PYRAMID 
program. 
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— Textured Pyramid 


FIGURE 8.5 Output from the PYRAMID sample program. 


LISTING 8.1 The PYRAMID Sample Program Source Code 


// Pyramid.c 

// Demonstrates Simple Texture Mapping 

// OpenGL SuperBible 

// Richard S. Wright Jr. 

#include "../../Common/OpenGLSB.h"“ // System and OpenGL Stuff 
#include "../../Common/GLTools.h" // GLTools 


// Rotation amounts 
static GLfloat xRot 
static GLfloat yRot 


0.0f; 
Q.0f; 


// Change viewing volume and viewport. Called when window is resized 
void ChangeSize(int w, int h) 

{ 

GLfloat fAspect; 


// Prevent a divide by zero 
if(h == Q) 
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LISTING 8.1 Continued 


// Set Viewport to window dimensions 
glViewport(@, @, w, h); 


fAspect = (GLfloat)w/(GLfloat)h; 


// Reset coordinate system 
glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 


// Produce the perspective projection 
gluPerspective(35.0f, fAspect, 1.0, 40.0); 


glMatrixMode(GL_MODELVIEW) ; 
glLoadIdentity(); 


} 


// This function does any needed initialization on the rendering 
// context. Here it sets up and initializes the lighting for 
// the scene. 
void SetupRC() 
{ 
GLubyte *pBytes; 
GLint iWidth, iHeight, iComponents; 
GLenum eFormat; 


// Light values and coordinates 

GLfloat whiteLight[] = { 0.05f, 0.05f, 0.05f, 1.0f }; 
GLfloat sourceLight[] = { 0.25f, 0.25f, 0.25f, 1.0f }; 
GLfloat lightPos[] = { -10.f, 5.0f, 5.0f, 1.0f }; 


glEnable(GL_DEPTH_TEST); // Hidden surface removal 
glFrontFace(GL_CCwW) ; // Counter clock-wise polygons face out 
qlEnable(GL_CULL_FACE) ; // Do not calculate inside of jet 


// Enable lighting 
glEnable(GL_LIGHTING) ; 


// Setup and enable light 0 
glLightModelfv(GL_LIGHT_MODEL_AMBIENT,whiteLight) ; 
glLightfv(GL_LIGHT®,GL_AMBIENT,sourceLight) ; 
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LISTING 8.1 Continued 


glLightfv(GL_LIGHT®,GL_DIFFUSE, sourceLight) ; 
glLightfv(GL_LIGHT@,GL_POSITION, lightPos) ; 
glEnable(GL_LIGHT®) ; 


// Enable color tracking 
glEnable(GL_COLOR_ MATERIAL) ; 


// Set Material properties to follow glColor values 
glColorMaterial(GL_FRONT, GL_AMBIENT_AND DIFFUSE) ; 


// Black blue background 
glClearColor(0.0f, 0.0f, 0.0f, 1.0f ); 


// Load texture 
glPixelStorei(GL_UNPACK_ALIGNMENT, 1); 
pBytes = gltLoadTGA("Stone.tga", &iWidth, &iHeight, 
&iComponents, &eFormat); 
glTexImage2D(GL_TEXTURE_2D, @, iComponents, iWidth, iHeight, 
@, eFormat, GL_UNSIGNED BYTE, pBytes); 
free(pBytes) ; 


glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN FILTER, GL_LINEAR); 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG FILTER, GL_LINEAR); 

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP TO EDGE); 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE); 


glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE) ; 
glEnable(GL_TEXTURE_2D) ; 
} 


// Respond to arrow keys 
void Specialkeys(int key, int x, int y) 
{ 
if(key == GLUT_KEY_UP) 
xRot-= 5.0f; 


if(key == GLUT_KEY_DOWN) 
xRot += 5.0f; 


if(key == GLUT_KEY_LEFT) 
yRot -= 5.0f; 
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LISTING 8.1 Continued 


if(key == GLUT_KEY_RIGHT) 
yRot += 5.0f; 


xRot 
yRot 


u 


(GLfloat)((const int)xRot % 360); 
(GLfloat)((const int)yRot % 360); 


// Refresh the Window 
glutPostRedisplay(); 
} 


// Called to draw scene 
void RenderScene(void) 


{ 
GLTVector3 vNormal; 
GLTVector3 vCorners[5] = { { @.O0f, .80f, 0.Of }, // Top () 
{ -0.5f, 0.0f, -.50f }, // Back left 1 
{ 0.5f, @.O0f, -0.50f }, // Back right 2 
{ O.5f, O.0f, @.5f }, // Front right 3 
4 


{ -0.5f, 0.0f, O.5f }}; // Front left 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 


// Save the matrix state and do the rotations 
glPushMatrix(); 
// Move object back and do in place rotation 
glTranslatef(0.0f, -@.25f, -4.0f); 
glRotatef(xRot, 1.0f, 0.0f, 0.0f); 
glRotatef(yRot, @.0f, 1.0f, @.0f); 


// Draw the Pyramid 

glColor3f(1.0f, 1.0f, 1.0f); 

g1Begin(GL_TRIANGLES) ; 
// Bottom section - two triangles 
glNormal3f(0.0f, -1.0f, 0.0f); 
glTexCoord2f(1.0f, 1.0f); 
glVertex3fv(vCorners[2]); 


glTexCoord2f(0.0f, 0.0f); 
glVertex3fv(vCorners[4]); 
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LISTING 8.1 Continued 


glTexCoord2f(0.0f, 1.0f); 
glVertex3fv(vCorners[1]); 


glTexCoord2f(1.0f, 1.0f); 
glVertex3fv(vCorners[2]); 


glTexCoord2f(1.0f, 0.0f); 
glVertex3fv(vCorners[3]) ; 


glTexCoord2f(0.0f, 0.0f); 
glVertex3fv(vCorners[4]) ; 


// Front Face 

gltGetNormalVector(vCorners[0], vCorners[4], vCorners[3], vNormal) ; 
glNormal3fv(vNormal) ; 

glTexCoord2f(0.5f, 1.0f); 

glVertex3fv(vCorners[Q]); 

glTexCoord2f(0.0f, 0.0f); 

glVertex3fv(vCorners[4]); 

glTexCoord2f(1.0f, 0.0f); 

glVertex3fv(vCorners[3]) ; 


// Left Face 

gltGetNormalVector(vCorners[0], vCorners[1], vCorners[4], vNormal) ; 
glNormal3fv(vNormal) ; 

glTexCoord2f(0.5f, 1.0f); 

glVertex3fv(vCorners[Q]) ; 

glTexCoord2f(0.0f, 0.0f); 

glVertex3fv(vCorners[1]); 

glTexCoord2f(1.0f, 0.0f); 

glVertex3fv(vCorners[4]); 


// Back Face 

gltGetNormalVector(vCorners[®], vCorners[2], vCorners[1], vNormal) ; 
glNormal3fv(vNormal) ; 

glTexCoord2f(0.5f, 1.0f); 

glVertex3fv(vCorners[Q]); 


glTexCoord2f(0.0f, @.0f); 
glVertex3fv(vCorners[2]); 
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glTexCoord2f(1.0f, 0.0f); 
glVertex3fv(vCorners[1]); 


// Right Face 
gltGetNormalVector(vCorners[®], vCorners[3], vCorners[2], vNormal); 
glNormal3fv(vNormal) ; 
glTexCoord2f(0.5f, 1.0f); 
glVertex3fv(vCorners[Q]); 
glTexCoord2f(0.0f, 0.0f); 
glVertex3fv(vCorners[3]); 
glTexCoord2f(1.0f, 0.O0f); 
glVertex3fv(vCorners[2]); 
glEnd(); 


// Restore the matrix state 
glPopMatrix(); 


// Buffer swap 
glutSwapBuffers(); 
} 


int main(int argc, char *argv[]) 
{ 
glutInit(&argce, argv); 
glutInitDisplayMode(GLUT_DOUBLE | GLUT_RGB | GLUT_DEPTH) ; 
glutInitWindowSize(800, 600); 
glutCreateWindow( "Textured Pyramid"); 
glutReshapeFunc(ChangeSize) ; 
glutSpecialFunc(Specialkeys) ; 
glutDisplayFunc(RenderScene) ; 
SetupRC(); 
glutMainLoop(); 


return Q; 


} 


The SetupRC function does all the necessary initialization for this program, including 
loading the texture using the gltLoadTGA function presented in the preceding chapter and 
supplying the bits to the g1TexImage2D function: 
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// Load texture 
pBytes = gltLoadTGA("Stone.tga", &iWidth, &iHeight, 
&iComponents, &eFormat) ; 
glTexImage2D(GL_TEXTURE_2D, @, iComponents, iWidth, iHeight, 
®, eFormat, GL_UNSIGNED_BYTE, pBytes) ; 
free(pBytes) ; 


Of course, texture mapping must also be turned on: 


glEnable(GL_TEXTURE_2D) ; 


The RenderScene function draws the pyramid as a series of texture-mapped triangles. The 
following excerpt shows one face being constructed as a normal (calculated using the 
corner vertices) is specified for the face, followed by three texture and vertex coordinates: 


// Front Face 

gltGetNormalVector(vCorners[®], vCorners[4], vCorners[3], vNormal) ; 
glNormal3fv(vNormal) ; 

glTexCoord2f(0.5f, 1.0f); 

glVertex3fv(vCorners[Q]); 

glTexCoord2f(0.0f, 0.0f); 

glVertex3fv(vCorners[4]); 

glTexCoord2f(1.0f, @.0f); 

glVertex3fv(vCorners[3]); 


Texture Environment 


In the PYRAMID sample program, the pyramid is drawn with white material properties, 
and the texture is applied in such a way that its colors are scaled by the coloring of the lit 
geometry. Figure 8.6 shows the untextured pyramid alongside the source texture and the 
textured but shaded pyramid. 


FIGURE 8.6 Lit Geometry + Texture = Shaded Texture. 


How OpenGL combines the colors from texels with the color of the underlying geometry 
is controlled by the texture environment mode. You set this mode by calling the glTexEnv 
function: 
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void glTexEnvi(GLenum target, GLenum pname, GLint param); 
void glTexEnvf(GLenum target, GLenum pname, GLfloat param); 
void glTexEnviv(GLenum target, GLenum pname, GLint *param); 
void glTexEnvfv(GLenum target, GLenum pname, GLfloat *param); 


This function comes in a variety of flavors, as shown here, and controls a number of more 
advanced texturing options covered in the next chapter. In the PYRAMID sample program, 
this function set the environment mode to GL_MODULATE before any texture application 
was performed: 


glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE) ; 


The modulate environment mode multiplies the texel color by the geometry color (after 
lighting calculations). This is why the shaded color of the pyramid comes through and 
makes the texture appear to be shaded. Using this mode, you can change the color tone of 
textures by using colored geometry. For example, a black-and-white brick texture applied 
to red, yellow, and brown geometry would yield red, yellow, and brown bricks with only a 
single texture. 


If you want to simply replace the color of the underlying geometry, you can specify 
GL_REPLACE for the environment mode. Doing so replaces fragment colors from the geom- 
etry directly with the texel colors. Making this change eliminates any effect on the texture 
from the underlying geometry. If the texture has an alpha channel, you can enable blend- 
ing, and you can use this mode to create transparent geometry patterned after the alpha 
channel in the texture map. 


If the texture doesn’t have an alpha component, GL_DECAL behaves the same way as 
GL_REPLACE. It simply “decals” the texture over the top of the geometry and any color 
values that have been calculated for the fragments. However, if the texture has an alpha 
component, the decal can be applied in such a way that the geometry shows through 
where the alpha is blended with the underlying fragments. 


Textures can also be blended with a constant blending color using the GL_BLEND texture 
environment. If you set this environment mode, you must also set the texture environ- 
ment color: 


GLfloat fColor[4] = { 1.0f, 0.0f, 0.0f, 0.0f }; 
glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_BLEND); 
glTexEnvfv(GL_TEXTURE_ENV, GL_TEXTURE_ENV_COLOR, fColor); 


Finally, you can simply add texel color values to the underlying fragment values by setting 
the environment mode to GL_ADD. Any color component values that exceed 1.0 are 
clamped, and you may get saturated color values (basically, white or closer to white than 
you might intend). 
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We have not presented an exhaustive list of the texture environment constants here. See 
the reference section and next chapter for more modes and texturing effects that are 
enabled and controlled through this function. We also revisit some additional uses in 
coming sections and sample programs. 


Texture Parameters 


More effort is involved in texture mapping than slapping an image on the side of a trian- 
gle. Many parameters affect the rendering rules and behaviors of texture maps as they are 
applied. These texture parameters are all set via variations on the function 
glTexParameter: 


void glTexParameterf(GLenum target, GLenum pname, GLfloat param) ; 
void glTexParameteri(GLenum target, GLenum pname, GLint param) ; 
void glTexParameterfv(GLenum target, GLenum pname, GLfloat *params) ; 
void glTexParameteriv(GLenum target, GLenum pname, GLint *params) ; 


The first argument, target, specifies which texture mode the parameter is to be applied to 
and may be either GL_TEXTURE_1D, GL_TEXTURE_2D, or GL_TEXTURE_3D. The second argu- 
ment, pname, specifies which texture parameter is being set, and finally, the param or 
params arguments set the value of the particular texture parameter. 


Basic Filtering 


Unlike pixmaps being drawn to the color buffer, when a texture is applied to geometry, 
there is almost never a one-to-one correspondence between texels in the texture map and 
pixels on the screen. A careful programmer could achieve this result, but only by texturing 
geometry that was carefully planned to appear onscreen such that the texels and pixels 
lined up. Consequently, texture images are always either stretched or shrunk as they are 
applied to geometric surfaces. Because of the orientation of the geometry, a given texture 
could even be stretched and shrunk at the same time across the surface of some object. 


The process of calculating color fragments from a stretched or shrunken texture map is 
called texture filtering. Using the texture parameter function, OpenGL allows you to set 
both magnification and minification filters. The parameter names for these two filters are 
GL_TEXTURE_MAG_FILTER and GL_TEXTURE_MIN_FILTER. You can select two basic texture 
filters for them, GL_NEAREST and GL_LINEAR, which correspond to nearest neighbor and 
linear filtering. 


Nearest neighbor filtering is the simplest and fastest filtering method you can choose. 
Texture coordinates are evaluated and plotted against a texture’s texels, and whichever 
texel the coordinate falls in, that color is used for the fragment texture color. Nearest 
neighbor filtering is characterized by large blocky pixels when the texture is stretched 
especially large. An example is shown in Figure 8.7. You can set the texture filter (for 
GL_TEXTURE_2D) for both the minification and magnification filter by using these two 
function calls: 
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glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG FILTER, GL_NEAREST) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST) ; 


FIGURE 8.7 Nearest neighbor filtering up close. 


Linear filtering requires more work than nearest neighbor, but often is worth the extra 
overhead. On today’s commodity hardware, the extra cost of linear filtering is negligible. 
Linear filtering works by not taking the nearest texel to the texture coordinate, but by 
applying the weighted average of the texels surrounding the texture coordinate (a linear 
interpolation). For this interpolated fragment to match the texel color exactly, the texture 
coordinate needs to fall directly in the center of the texel. Linear filtering is characterized 
by “fuzzy” graphics when a texture is stretched. This fuzziness, however, often lends to a 
more realistic and less artificial look than the jagged blocks of the nearest neighbor filter- 
ing mode. A contrasting example to Figure 8.7 is shown in Figure 8.8. You can set linear 
filtering (for GL_TEXTURE_2D) simply enough by using the following lines, which are also 
included in the SetupRC function in the PYRAMID example: 


glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG FILTER, GL_LINEAR) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE MIN FILTER, GL_LINEAR) ; 
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FIGURE 8.8 Linear filtering up close. 


Texture Wrap 


Normally, you specify texture coordinates between 0.0 and 1.0 to map out the texels in a 
texture map. If texture coordinates fall outside this range, OpenGL handles them accord- 
ing to the current texture wrapping mode. You can set the wrap mode for each coordinate 
individually by calling gl1TexParameteri with GL_TEXTURE_WRAP_S, GL_TEXTURE_WRAP_T, or 
GL_TEXTURE_WRAP_R as the parameter name. The wrap mode can then be set to one of the 
following values: GL_REPEAT, GL_CLAMP, GL_CLAMP_TO_EDGE, or GL_CLAMP_TO_BORDER. 


The GL_REPEAT wrap mode simply causes the texture to repeat in the direction in which 
the texture coordinate has exceeded 1.0. The texture repeats again for every integer texture 
coordinate. This mode is very useful for applying a small tiled texture to large geometric 
surfaces. Well-done seamless textures can lend the appearance of a seemingly much larger 
texture, but at the cost of a much smaller texture image. The other modes do not repeat, 
but are “clamped”—thus their name. 


If the only implication of the wrap mode is whether the texture repeats, you would need 
only two wrap modes: repeat and clamp. However, the texture wrap mode also has a great 
deal of influence on how texture filtering is done at the edges of the texture maps. For 
GL_NEAREST filtering, there are no consequences to the wrap mode because the texture 
coordinates are always snapped to some particular texel within the texture map. However, 
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the GL_LINEAR filter takes an average of the pixels surrounding the evaluated texture coor- 
dinate, and this creates a problem for texels that lie along the edges of the texture map. 


This problem is resolved quite neatly when the wrap mode is GL_REPEAT. The texel 
samples are simply taken from the next row or column, which in repeat mode wraps back 
around to the other side of the texture. This mode works perfectly for textures that wrap 
around an object and meet on the other side (such as spheres). 


The clamped texture wrap modes offer a number of options for the way texture edges are 
handled. For GL_CLAMP, the needed texels are taken from the texture border or the 
TEXTURE_BORDER_COLOR (set with glTexParameterfv). The GL_CLAMP_TO_EDGE wrap mode 
simply ignores texel samples that go over the edge and does not include them in the 
average. Finally, GL__CLAMP_TO_BORDER uses only border texels whenever the texture coordi- 
nates fall outside the range 0.0 to 1.0. 


A typical application of the clamped modes occurs when you must texture a large area 
that would require a single texture too large to fit into memory, or that may be loaded 
into a single texture map, In this case, the area is chopped up into smaller “tiles” that are 
then placed side by side. In such a case, not using a wrap mode such as GL_CLAMP_TO_EDGE 
causes visible filtering artifacts along the seams between tiles. 


In the PYRAMID sample program, texture coordinates along the bottom of the pyramid 
might leave a dark seam, except that you have set the wrap mode to clamp the bilinear 
filtering to within the texture map: 


glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO EDGE); 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO EDGE); 


Cartoons with Texture 

The first example for this chapter used 2D textures because they are usually the simplest 
and easiest to understand. Most people can quickly get an intuitive feel for putting a 2D 
picture on the side of a piece of 2D geometry (such as a triangle). We will step back now 
and present a one-dimensional texture mapping example that is commonly used in 
computer games to render geometry that appears onscreen shaded like a cartoon. Toon- 
shading, which is often referred to as cell-shading, uses a one-dimensional texture map as a 
lookup table to fill in geometry with a solid color (using GL_NEAREST) from the texture 
map. 


The basic idea is to use a surface normal from the geometry and a normal from the light 
source to find the intensity of the light striking the surface of the model. The dot product 
of these two vectors gives a value between 0.0 and 1.0 and is used as a one-dimensional 
texture coordinate. The sample program TOON presented in Listing 8.2 draws a green 
torus using this technique. The output from TOON is shown in Figure 8.9. 
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FIGURE 8.9 A cell-shaded torus. 


LISTING 8.2 Source Code for the TOON Sample Program 


// Toon.c 

// OpenGL SuperBible 

// Demonstrates Cell/Toon shading with a 1D texture 
// Program by Richard S. Wright Jr. 


#include "../../Common/OpenGLSB.h" // System and OpenGL Stuff 
#include "../../Common/GLTools.h" // OpenGL toolkit 
#include <math.h> 


// Draw a torus (doughnut), using the current 1D texture for light shading 
void toonDrawTorus(GLfloat majorRadius, GLfloat minorRadius, 
int numMajor, int numMinor, GLTVector3 vLightDir) 

{ 

GLTMatrix mModelViewMatrix; 

GLTVector3 vNormal, vTransformedNormal; 

double majorStep = 2.@f*GLT_PI / numMajor; 

double minorStep = 2.0f*GLT_PI / numMinor; 

int i;.-}; 


i] 
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// Get the modelview matrix 
glGetFloatv(GL_MODELVIEW_MATRIX, mModelViewMatrix) ; 


// Normalize the light vector 
gltNormalizeVector(vLightDir) ; 


// Draw torus as a series of triangle strips 
for (i=; i<numMajor; ++i) 

{ 

double a® = i * majorStep; 

double a1 = aQ@ + majorStep; 

GLfloat x® = (GLfloat) cos(aQ); 

GLfloat yo (GLfloat) sin(aQ); 

GLfloat x1 = (GLfloat) cos(a1); 

GLfloat y1 (GLfloat) sin(a1); 


glBegin(GL_TRIANGLE_STRIP) ; 
for (j=; j<=numMinor; ++j) 

{ 

double b = j * minorStep; 


GLfloat c = (GLfloat) cos(b); 
GLfloat r = minorRadius * c + majorRadius; 
GLfloat z = minorRadius * (GLfloat) sin(b); 


// First point 

vNormal[®] = x@*c; 

vNormal[1] = yQ*c; 

vNormal[2] = z/minorRadius; 

gltNormalizeVector(vNormal) ; 

gltRotateVector(vNormal, mModelViewMatrix, vTransformedNormal) ; 


// Texture coordinate is set by intensity of light 
glTexCoordif(gltVectorDotProduct(vLightDir, vTransformedNormal) ) ; 
glVertex3f(x@*r, yO*r, z); 


// Second point 

vNormal[@] = x1*c; 

vNormal[1] = y1*c; 

vNormal[2] = z/minorRadius; 

gltNormalizeVector(vNormal) ; 

gltRotateVector(vNormal, mModelViewMatrix, vTransformedNormal) ; 
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// Texture coordinate is set by intensity of light 
glTexCoord1f(gltVectorDotProduct(vLightDir, vTransformedNormal) ) ; 
glVertex3f(x1*r, yi*r, Z); 
} 

glEnd(); 

} 


// Called to draw scene 
void RenderScene(void) 
{ 
// Rotation angle 
static GLfloat yRot = 0.0f; 


// Where is the light coming from 
GLTVector3 vLightDir = { -1.0f, 1.0f, 1.0f }; 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 
glPushMatrix(); 
glTranslatef(0.0f, @.0f, -2.5f); 
glRotatef(yRot, 0.0f, 1.0f, 0.0f); 
toonDrawTorus(®.35f, @.15f, 50, 25, vLightDir) ; 
glPopMatrix(); 


// Do the buffer Swap 
glutSwapBuffers(); 


// Rotate 1/2 degree more each frame 
yRot += 0.5f; 
} 


// This function does any needed initialization on the rendering 
// context. 
void SetupRC() 

{ 

// Load a 1D texture with toon shaded values 

// Green, greener... 

GLbyte toonTable[4][3] = { { @, 32, @ }, 

{ 0, 64, 0}, 
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{ @, 128, @ }, 
{ @, 192, ® }}; 


// Bluish background 
glClearColor(0.0f, @.0f, .50f, 1.0f ); 
glEnable(GL_DEPTH_TEST) ; 
glEnable(GL_CULL_FACE) ; 


glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_DECAL); 

glTexParameteri(GL_TEXTURE_1D, GL_TEXTURE_MAG FILTER, GL_NEAREST); 

glTexParameteri(GL_TEXTURE_1D, GL_TEXTURE_MIN FILTER, GL_NEAREST); 

glTexParameteri(GL_TEXTURE_1D, GL_TEXTURE_WRAP_S, GL_CLAMP); 

glPixelStorei(GL_UNPACK_ALIGNMENT, 1); 

glTexImage1D(GL_TEXTURE_1D, ®, GL_RGB, 4, 0, GL_RGB, 
GL_UNSIGNED_BYTE, toonTable); 


glEnable(GL_TEXTURE_1D) ; 
} 


FUTTTTTTT ATTA TAT AD 
// Called by GLUT library when idle (window not being 
// resized or moved) 
void TimerFunction(int value) 
{ 
// Redraw the scene with new coordinates 
glutPostRedisplay(); 
glutTimerFunc(33,TimerFunction, 1); 


} 


void ChangeSize(int w, int h) 


{ 
GLfloat fAspect; 


// Prevent a divide by zero, when window is too short 


// (you can't make a window of zero width). 
if(h == @) 


glViewport(®@, ®, w, h); 
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LISTING 8.2 Continued 
fAspect = (GLfloat)w / (GLfloat)h; 


// Reset the coordinate system before modifying 
glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 


// Set the clipping volume 
gluPerspective(35.0f, fAspect, 1.0f, 50.0f); 


glMatrixMode(GL_MODELVIEW) ; 
glLoadIdentity(); 
} 


FLTTTTT TTT TTT TTT TTT 
// Program entry point 
int main(int argc, char* argv[]) 
{ 
glutInit(&argc, argv); 
glutInitDisplayMode(GLUT_DOUBLE | GLUT_RGB | GLUT_DEPTH) ; 
glutInitWindowSize (800,600) ; 
glutCreateWindow("Toon/Cell Shading Demo") ; 
glutReshapeFunc(ChangeSize) ; 
glutDisplayFunc(RenderScene) ; 
glutTimerFunc(33, TimerFunction, 1); 


SetupRC(); 
glutMainLoop(); 


return Q; 


} 


Mipmapping 

Mipmapping’is a powerful texturing technique that can improve both the rendering perfor- 
mance and visual quality of a scene. It does this by addressing two common problems 
with standard texture mapping. The first is an effect called scintillation (aliasing artifacts) 
that appears on the surface of objects rendered very small onscreen compared to the rela- 
tive size of the texture applied. Scintillation can be seen as a sort of sparkling that occurs 
as the sampling area on a texture map moves disproportionately to its size on the screen. 
The negative effects of scintillation are most noticeable when the camera or the objects are 
in motion. 


Texture Parameters 401 


The second issue is more performance related, but is due to the same scenario that leads to 
scintillation. That is, a large amount of texture memory must be loaded and processed 
through filtering to display a small number of fragments onscreen. This causes texturing 
performance to suffer greatly as the size of the texture increases. 


The solution to both of these problems is to simply use a smaller texture map. However, 
this solution then creates a new problem, that when near the same object, it must be 
rendered larger, and a small texture map will then be stretched to the point of creating a 
hopelessly blurry or blocky textured object. 


The solution to both of these issues is mipmapping. Mipmapping” gets its name from the 
Latin phrase multum in parvo, which means “many things in a small place.” In essence, 
you load not a single image into the texture state, but a whole series of images from 
largest to smallest into a single “mipmapped” texture state. OpenGL then uses a new set of 
filter modes to choose the best-fitting texture or textures for the given geometry. At the 
cost of some extra memory (and possibly considerably more processing work), you can 
eliminate scintillation and the texture memory processing overhead for distant objects 
simultaneously, while maintaining higher resolution versions of the texture available 
when needed. 


A mipmapped texture consists of a series of texture images, each one half the size of the 
previous image. This scenario is shown in Figure 8.10. Mipmap levels do not have to be 
square, but the halving of the dimensions continues until the last image is 1x1 texel. 
When one of the dimensions reaches 1, further divisions occur on the other dimension 
only. Using a square set of mipmaps requires about one third more memory than not 
using mipmaps. 


FIGURE 8.10 A series of mipmapped images. 


Mipmap levels are loaded with g1TexImage. Now the level parameter comes into play 
because it specifies which mip level the image data is for. The first level is 0, then 1, 2, and 
so on. If mipmapping”is not being used, only level 0 is ever loaded. By default, to use 
mipmaps, all mip levels must be populated. You can, however, specifically set the base and 
maximum levels to be used with the GL_TEXTURE_BASE_LEVEL and GL_TEXTURE_MAX_LEVEL 
texture parameters. For example, if you want to specify that only mip levels 0 through 4 
need to be loaded, you call g1TexParameteri twice as follows: 
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glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_BASE_LEVEL, Q); 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAX_LEVEL, 4); 


Although GL_TEXTURE_BASE_LEVEL and GL_TEXTURE_MAX_LEVEL control which mip levels 
are loaded, you can also specifically limit the range of loaded mip levels to be used by 
using the parameters GL_TEXTURE_MIN_LOD and GL_TEXTURE_MAX_LOD instead. 


Mipmap Filtering 

Mipmapping adds a new twist to the two basic texture filtering modes GL_NEAREST and 
GL_LINEAR by giving four permutations for mipmapped filtering modes. They are listed in 
Table 8.4. 


TABLE 8.4 Mipmapped Texture Filters 


Constant Description 

GL_NEAREST Perform nearest neighbor filtering on the base mip level 

GL_LINEAR Perform linear filtering on the base mip level 

GL_NEAREST_MIPMAP_NEAREST Select the nearest mip level and perform nearest neighbor filtering 

GL_NEAREST_MIPMAP_LINEAR Perform a linear interpolation between mip levels and perform 
nearest neighbor filtering 

GL_LINEAR_MIPMAP_NEAREST Select the nearest mip level and perform linear filtering 

GL_LINEAR_MIPMAP_LINEAR Perform a linear interpolation between mip levels and perform linear 


filtering; also called trilinear mipmapping 


Just loading the mip levels with g1TexImage does not by itself enable mipmapping. If the 
texture filter is set to GL_LINEAR or GL_NEAREST, only the base texture level is used, and any 
mip levels loaded are ignored. You must specify one of the mipmapped filters listed for the 
loaded mip levels to be used. The constants have the form GL_FILTER_MIPMAP_SELECTOR, 
where FILTER specifies the texture filter to be used on the mip level selected. The SELECTOR 
specifies how the mip level is selected; for example, GL_NEAREST selects the nearest match- 
ing mip level. Using GL_LINEAR for the selector creates a linear interpolation between the 
two nearest mip levels, which is again filtered by the chosen texture filter. Selecting one of 
the mipmapped filtering modes without loading the mip levels has the effect of disabling 
texture mapping. 


Which filter you select varies depending on the application and the performance require- 
ments at hand. GL_NEAREST_MIPMAP_NEAREST, for example, gives very good performance 
and low aliasing (scintillation) artifacts, but nearest neighbor filtering is often not visually 
pleasing. GL_LINEAR_MIPMAP_NEAREST is often used to speed up games because a higher 
quality linear filter is used, but a fast selection (nearest) is made between the different 
sized mip levels available. 


Using nearest as the mipmap selector (as in both examples in the preceding paragraph), 
however, can also leave an undesirable visual artifact. For oblique views, you can often see 
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the transition from one mip level to another across a surface. It can be seen as a distortion 
line or a sharp transition from one level of detail to another. The 
GL_LINEAR_MIPMAP_LINEAR and GL_NEAREST_MIPMAP_LINEAR filters perform an additional 
interpolation between mip levels to eliminate this transition zone, but at the extra cost of 
substantially more processing overhead. The GL_LINEAR_MIPMAP_LINEAR filter is often 
referred to as trilinear mipmapping”and until recently was the gold standard (highest 
fidelity) of texture filtering. More recently, anisotropic texture filtering (covered in the next 
chapter) has become widely available on OpenGL hardware but even further increases the 
cost (performance wise) of texture mapping. 


Generating Mip Levels 

As mentioned previously, mipmapping” requires approximately one third more texture 
memory than just loading the base texture image. It also requires that all the smaller 
versions of the base texture image be available for loading. Sometimes this can be inconve- 
nient because the lower resolution images may not necessarily be available either to the 
programmer or the end user of your software. The GLU library does include a function 
named gluScaleImage (see the reference section) that you could use to repeatedly scale 
and load an image until all the needed mip levels are loaded. More frequently, however, 
an even more convenient function is available; it automatically creates the scaled images 
for you and loads them appropriately with g1TexImage. This function, gluBuildMipmaps, 
comes in three flavors and supports one-, two-, and three-dimensional texture maps: 


int gluBuildiDMipmaps(GLenum target, GLint internalFormat, 
GLint width, 
GLenum format, GLenum type, const void *data); 


int gluBuild2DMipmaps(GLenum target, GLint internalFormat, 
GLint width, GLint height, 
GLenum format, GLenum type, const void *data); 


int gluBuild3DMipmaps(GLenum target, GLint internalFormat, 
GLint width, GLint height, GLint depth, 
GLenum format, GLenum type, const void *data) ; 


The use of these functions closely parallels the use of g1TexImage, but they do not have a 
level parameter for specifying the mip level, nor do they provide any support for a 
texture border. You should also be aware that using these functions may not produce mip 
level images with the same quality you can obtain with other tools such as Photoshop. 
The GLU library uses a box filter to reduce images, which can lead to an undesirable loss of 
fine detail as the image shrinks. 


With newer versions of the GLU library, you can also obtain a finer-grained control over 
which mip levels are loaded with these functions: 


403 


404 


CHAPTER 8 Texture Mapping: The Basics 


int gluBuildiDMipmapLevels(GLenum target, GLint internalFormat, 
GLint width, 
GLenum format, GLenum type, GLint level, 
GLint base, GLint max, const void *data); 


int gluBuild2DMipmapLevels(GLenum target, GLint internalFormat, 
GLint width, GLint height, 
GLenum format, GLenum type, GLint level, 
GLint base, GLint max, const void *data); 


int gluBuild3DMipmapLevels(GLenum target, Glint internalFormat, 
GLint width, GLint height, GLint depth, 
GLenum format, GLenum type, GLint level, 
GLint base, GLint max, const void *data); 


With these functions, level is the mip level specified by the data parameter. This texture 
data is used to build mip levels base through max. 


Hardware Generation of Mipmaps__ If you know beforehand that you want all mip levels 
loaded, you can also use OpenGL hardware acceleration to quickly generate all the neces- 
sary mip levels. You do so by setting the texture parameter GL_GENERATE_MIPMAP to 
GL_TRUE: 


glTexParameteri(GL_TEXTURE_2D, GL_GENERATE_MIPMAP, GL_TRUE) ; 


When this parameter is set, all calls to g1TexImage or g1TexSubImage that update the base 
texture map (mip level 0) automatically update all the lower mip levels. By making use of 
the graphics hardware, this feature is substantially faster than using gluBuildMipmaps. 
However, you should be aware that this feature was originally an extension and was 
promoted to the OpenGL core API only as of version 1.4. 


LOD BIAS 

When mipmapping is enabled, OpenGL uses a formula to determine which mip level 
should be selected based on the size of the mipmap levels and the onscreen area the 
geometry occupies. OpenGL does its best to make a close match between the mipmap 
level chosen and the texture’s representation onscreen. You can tell OpenGL to move its 
selection criteria back (lean toward larger mip levels) or forward (lean toward smaller mip 
levels). This can have the effect of increasing performance (using smaller mip levels) or 
increasing the sharpness of texture-mapped objects (using larger mip levels). This bias one 
way or the other is selected with the texture environment parameter 
GL_TEXTURE_LOD_BIAS, as shown here: 


glTexEnvf (GL_TEXTURE_FILTER_CONTROL, GL_TEXTURE_LOD BIAS, -1.5); 
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In this example, the texture level of detail is shifted slightly toward using higher levels of 
detail (smaller level parameters), resulting in sharper looking textures, at the expense of 
slightly more texture processing overhead. 


Texture Objects 


So far, you have seen how to load a texture and set texture parameters to affect how 
texture maps are applied to geometry. The texture image and parameters set with 
glTexParameter comprise the texture state. Loading and maintaining the texture state 
occupies a considerable portion of many texture-heavy OpenGL applications (such as 
games in particular). 


Especially time consuming are function calls such as g1TexImage, g1TexSubImage, and 
gluBuildMipmaps. These functions move a large amount of memory around and possibly 
need to reformat the data to match some internal representation. Switching between 
textures or reloading a different texture image would ordinarily be a costly operation. 


Texture objects allow you to load up more than one texture state at a time, including 
texture images, and switch between them very quickly. The texture state is maintained by 
the currently bound texture object, which is identified by an unsigned integer. You allo- 
cate a number of texture objects with the following function: 


void glGenTextures(GLsizei n, GLuint *textures) ; 


With this function, you specify the number of texture objects and a pointer to an array of 
unsigned integers that will be populated with the texture object identifiers. You can think 
of them as handles to different available texture states. To “bind” to one of these states, 
you call the following function: 


void glBindTexture(GLenum target, GLuint texture); 


The target parameter needs to specify either GL_TEXTURE_1D, GL_TEXTURE_2D, or 
GL_TEXTURE_3D, and texture is the specific texture object to bind to. Hereafter, all texture 
loads and texture parameter settings affect only the currently bound texture object. To 
delete texture objects, you call the following function: 


void glDeleteTextures(GLsizei n, GLuint *textures); 


The arguments here have the same meaning as for glGenTextures. You do not need to 
generate and delete all your texture objects at the same time. Multiple calls to 
glGenTextures have very little overhead. Calling glDeleteTextures multiple times may 
incur some delay, but only because you are deallocating possibly large amounts of texture 
memory. 
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You can test texture object names (or handles) to see whether they are valid by using the 
following function: 


GLboolean glIsTexture(GLuint texture); 


This function returns GL_TRUE if the integer is a previously allocated texture object name 
or GL_FALSE if not. 


Managing Multiple Textures 

Generally, texture objects are used to load up several textures at program initialization and 
switch between them quickly during rendering. These texture objects are then deleted 
when the program shuts down. The TUNNEL sample program loads three textures at 
startup and then switches between them to render a tunnel. The tunnel has a brick wall 
pattern with different materials on the floor and ceiling. The output from TUNNEL is 
shown in Figure 8.11. 


FIGURE 8.11 A tunnel rendered with three different textures. 


The TUNNEL sample program also shows off mipmapping”and the different mipmapped 
texture filtering modes. Pressing the up- and down-arrow keys moves the point of view 
back and forth in the tunnel, and the context menu (right-click menu) allows you to 
switch among six different filtering modes to see how they affect the rendered image. The 
complete source code is provided in Listing 8.3. 
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LISTING 8.3 Source Code for the TUNNEL Sample Program 


// Tunnel.c 

// Demonstrates mipmapping"and using texture objects 

// OpenGL SuperBible 

// Richard S. Wright Jr. 

#include “../../Common/OpenGLSB.h" // System and OpenGL Stuff 
#include “../../Common/GLTools.h" // GLTools 


// Rotation amounts 
static GLfloat zPos = -60.0f; 


// Texture objects 
#define TEXTURE_BRICK 0 
#define TEXTURE_FLOOR 1 
#define TEXTURE_CEILING 2 
#define TEXTURE_COUNT 3 
GLuint textures[TEXTURE_COUNT] ; 
const char *szTextureFiles[TEXTURE_COUNT] = 
{ "brick.tga", “floor.tga", "ceiling.tga" }; 


LTLTTLTTT TTT TTT LL 
// Change texture filter for each texture object 
void ProcessMenu(int value) 

{ 

GLint iLoop; 


for(iLoop = @; iLoop < TEXTURE_COUNT; iLoop++) 
{ 
glBindTexture(GL_TEXTURE_2D, textures[iLoop]); 


switch(value) 
{ 
case 0: 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, 
GL_NEAREST) ; 
break; 
case 1: 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, 
GL_LINEAR) ; 


break; 
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LISTING 8.3 Continued 


case 2: 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, 
GL_NEAREST_MIPMAP_NEAREST) ; 


break; 


case 3: 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN FILTER, 
GL_NEAREST_MIPMAP_LINEAR) ; 
break; 


case 4: 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN FILTER, 
GL_LINEAR_MIPMAP_NEAREST) ; 
break; 


case 5: 
default: 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, 
GL_LINEAR_MIPMAP_LINEAR) ; 
break; 


// Trigger Redraw 
glutPostRedisplay() ; 
} 


TLTTTTTTT TTT TTT TTT TTT TL 
// This function does any needed initialization on the rendering 
// context. Here it sets up and initializes the texture objects. 
void SetupRC() 

{ 

GLubyte *pBytes; 

GLint iWidth, iHeight, iComponents; 

GLenum eFormat; 

GLint iLoop; 


// Black background 
glClearColor(0.0f, @.0f, 0.0f,1.0f); 
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// Textures applied as decals, no lighting or coloring effects 
glEnable(GL_TEXTURE_2D) ; 
glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_DECAL) ; 


// Load textures 

glGenTextures(TEXTURE_COUNT, textures) ; 

for(iLoop = @; iLoop < TEXTURE_COUNT; iLoop++) 
{ 
// Bind to next texture object 
glBindTexture(GL_TEXTURE_2D, textures[iLoop]) ; 


// Load texture, set filter and wrap modes 
pBytes = gltLoadTGA(szTextureFiles[iLoop] ,&iWidth, &iHeight, 
&iComponents, &eFormat) ; 
gluBuild2DMipmaps(GL_TEXTURE_2D, iComponents, iWidth, iHeight, eFormat, 
GL_UNSIGNED_BYTE, pBytes) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG FILTER, GL_LINEAR); 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, 
GL_LINEAR_MIPMAP_LINEAR) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE) ; 


// Don't need original texture data any more 
free(pBytes) ; 
} 


FETTTTTT TTT TAT TA AL 
// Shutdown the rendering context. Just deletes the 
// texture objects 
void ShutdownRC(void) 

{ 

glDeleteTextures(TEXTURE_COUNT, textures) ; 


} 


FUTTTTTT TTT AAT TT TT 
// Respond to arrow keys, move the viewpoint back 
// and forth 
void SpecialKeys(int key, int x, int y) 

{ 
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LISTING 8.3 Continued 


if (key == GLUT_KEY_UP) 
zPos += 1.0f; 


if(key == GLUT_KEY_DOWN) 
zPos -= 1.0f; 


// Refresh the Window 
glutPostRedisplay() ; 
} 


FETTTLTTAT TTT TTT TATA TATA 
// Change viewing volume and viewport. Called when window is resized 
void ChangeSize(int w, int h) 

{ 

GLfloat fAspect; 


// Prevent a divide by zero 
if(h == Q) 
h=1; 


// Set Viewport to window dimensions 
glViewport(®, ®, w, h); 


fAspect = (GLfloat)w/(GLfloat)h; 


// Reset coordinate system 
glMatrixMode(GL_PROJECTION) ; 
glLoadidentity(); 


// Produce the perspective projection 
gluPerspective(90.0f,fAspect, 1,120); 


glMatrixMode (GL_MODELVIEW) ; 
glLoadidentity(); 
} 


FELLTTTTTTT TTT TTT TTT TTT TT 
// Called to draw scene 
void RenderScene (void) 

{ 

GLfloat z; 
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// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Save the matrix state and do the rotations 
glPushMatrix() ; 
// Move object back and do in place rotation 
glTranslatef(0.0f, @.0f, zPos); 


// Floor 
for(z = 60.0f; z >= 0.0f; z -= 10) 
{ 
glBindTexture(GL_TEXTURE_2D, textures[TEXTURE_FLOOR]) ; 
glBegin(GL_QUADS) ; 
glTexCoord2f(0.0f, 0.0f); 
glVertex3f(-10.0f, -10.0f, z); 


glTexCoord2f(1.0f, 0.0f); 
glVertex3f(10.0f, -10.0f, z); 


glTexCoord2f(1.0f, 1.0f); 
glVertex3f(10.0f, -10.0f, z - 10.0f); 


glTexCoord2f(0.0f, 1.0f); 
glVertex3f(-10.0f, -10.0f, z - 10.0f); 
glEnd(); 


// Ceiling 
glBindTexture(GL_TEXTURE_2D, textures[TEXTURE_CEILING]) ; 
glBegin(GL_QUADS) ; 

glTexCoord2f(0.0f, 1.0f); 

glVertex3f(-10.0f, 10.0f, z - 10.0f); 


glTexCoord2f(1.0f, 1.0f); 
glVertex3f(10.0f, 10.0f, z - 10.0f); 


glTexCoord2f(1.0f, 0.0f); 
glVertex3f(10.0f, 10.0f, z); 


glTexCoord2f(0@.0f, 0.0f); 
glVertex3f(-10.0f, 10.0f, z); 
glEnd(); 
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LISTING 8.3 Continued 


// Left Wall 
glBindTexture(GL_TEXTURE_2D, textures[TEXTURE_BRICK]) ; 
glBegin(GL_QUADS) ; 

glTexCoord2f(0.0f, 0.0f); 

glVertex3f(-10.0f, -10.0f, z); 


glTexCoord2f(1.0f, 0.0f); 
glVertex3f(-10.0f, -10.0f, z - 10.0f); 


glTexCoord2f(1.0f, 1.0f); 
glVertex3f(-10.0f, 10.0f, z - 10.0f); 


glTexCoord2f(0.0f, 1.0f); 
glVertex3f(-10.0f, 10.0f, z); 
glEnd(); 


// Right Wall 

g1Begin(GL_QUADS) ; 
glTexCoord2f(0.0f, 1.0f); 
glVertex3f(10.0f, 10.0f, z); 


glTexCoord2f(1.0f, 1.0f); 
glVertex3f(10.0f, 10.0f, z - 10.0f); 


glTexCoord2f(1.0f, 0.0f); 
glVertex3f(10.0f, -10.@f, z - 10.0f); 


glTexCoord2f(0.0f, 0.0f); 
glVertex3f(10.0f, -10.0f, z); 
glEnd(); 
} 


// Restore the matrix state 
glPopMatrix() ; 


// Buffer swap 
glutSwapBuffers() ; 
} 


FTTTTTTT TTT TTT TTT TTT TTT TTT TL 
// Program entry point 
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int main(int argc, char *argv[]) 
{ 
// Standard initialization stuff 
glutInit(&argc, argv); 
glutInitDisplayMode(GLUT_DOUBLE | GLUT_RGB) ; 
glutInitWindowSize(800, 600); 
glutCreateWindow( "Tunnel") ; 
glutReshapeFunc(ChangeSize) ; 
glutSpecialFunc(SpecialKeys) ; 
glutDisplayFunc(RenderScene) ; 


// Add menu entries to change filter 
glutCreateMenu(ProcessMenu) ; 

glutAddMenuEntry ("GL_NEAREST" ,Q) ; 
glutAddMenuEntry("GL_LINEAR",1) ; 
glutAddMenuEntry ( "GL_NEAREST_MIPMAP_NEAREST" , 2) ; 
glutAddMenuEntry ("GL_NEAREST_MIPMAP_LINEAR", 3) ; 
glutAddMenuEntry("“GL_LINEAR_MIPMAP_NEAREST", 4); 
glutAddMenuEntry("GL_LINEAR_MIPMAP_LINEAR", 5); 
glutAttachMenu(GLUT_RIGHT_BUTTON) ; 


// Startup, loop, shutdown 
SetupRC(); 

glutMainLoop(); 
ShutdownRC() ; 


return 0; 


} 


In this example, you first create identifiers for the three texture objects. The array 
textures will contain three integers, which will be addressed by using the macros 
TEXTURE_BRICK, TEXTURE_FLOOR, and TEXTURE_CEILING. For added flexibility, you also create 
a macro that defines the maximum number of textures that will be loaded and an array of 
character strings containing the names of the texture map files: 


// Texture objects 
#define TEXTURE_BRICK 0 
#define TEXTURE_FLOOR 1 
#define TEXTURE_CEILING 2 
#define TEXTURE_COUNT 3 
GLuint textures[TEXTURE_COUNT] ; 
const char *szTextureFiles[TEXTURE_COUNT] = 
{ "brick.tga", "floor.tga", "ceiling.tga" }; 
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The texture objects are allocated in the SetupRC function: 


glGenTextures(TEXTURE_COUNT, textures) ; 


Then a simple loop binds to each texture object in turn and loads its texture state with the 
texture image and texturing parameters: 


for(iLoop = @; iLoop < TEXTURE_COUNT; iLoop++) 
{ 
// Bind to next texture object 
glBindTexture(GL_TEXTURE_2D, textures[iLoop]) ; 


// Load texture, set filter and wrap modes 
pBytes = gltLoadTGA(szTextureFiles[iLoop],&iWidth, &iHeight, 
&iComponents, &eFormat) ; 
gluBuild2DMipmaps(GL_TEXTURE_2D, iComponents, iWidth, iHeight, eFormat, 
GL_UNSIGNED_ BYTE, pBytes); 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, 
GL_LINEAR_MIPMAP_LINEAR) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE) ; 


// Don't need original texture data any more 
free(pBytes) ; 
} 


With each of the three texture objects initialized, you can easily switch between them 
during rendering to change textures: 


glBindTexture(GL_TEXTURE_2D, textures[TEXTURE_FLOOR]) ; 
glBegin(GL_QUADS) ; 
glTexCoord2f(0.0f, 0.0f); 
glVertex3f(-10.0f, -10.0f, z); 


glTexCoord2f(1.0f, @.0f); 
glVertex3f(10.0f, -10.0f, z); 


Finally, when the program is terminated, you only need to delete the texture objects for 
the final cleanup: 
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TLTTTTTTTT TTT ATT TL 
// Shutdown the rendering context. Just deletes the 
// texture objects 
void ShutdownRC( void) 

{ 

glDeleteTextures(TEXTURE COUNT, textures); 

} 


Also, note that when the mipmapped texture filter is set in the TUNNEL sample program, 
it is selected only for the minification filter: 


glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG FILTER, GL_LINEAR) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN FILTER, GL_LINEAR_MIPMAP_LINEAR) ; 


This is typically the case because after OpenGL selects the largest available mip level, no 
larger levels are available to select between. Essentially, this is to say that once a certain 
threshold is passed, the largest available texture image is used and there are no additional 
mipmap levels to choose from. 


Resident Textures 

Most OpenGL implementations support a limited amount of high-performance texture 
memory. Textures located in this memory are accessed very quickly, and performance is 
high. Initially, any loaded texture is stored in this memory; however, only a limited 
amount of memory is typically available, and at some point textures may need to be 
stored in slower memory. As is often the case, this slower memory may even be located 
outside the OpenGL hardware (such as in a PC’s system memory as opposed to being 
stored on the graphics card or in AGP memory). 


To optimize rendering performance, OpenGL automatically moves frequently accessed 
textures into this high-performance memory. Textures in this high-performance memory 
are called resident textures. To determine whether a bound texture is resident, you can call 
glGetTexParameter and find the value associated with GL_TEXTURE_RESIDENT. Testing a 
group of textures to see whether they are resident may be more useful, and you can 
perform this test using the following function: 


GLboolean glAreTexturesResident(GLsizei n, const GLuint *textures, 
GLboolean *residences) ; 


This function takes the number of texture objects to check, an array of the texture object 
names, and finally an array of Boolean flags set to GL_TRUE or GL_FALSE to indicate the 
status of each texture object. If all the textures are resident, the array is left unchanged, 
and the function returns GL_TRUE. This feature is meant to save the time of having to 
check through an entire array to see whether all the textures are resident. 
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Texture Priorities 

By default, most OpenGL implementations use a Most Frequently Used (MFU) algorithm 
to decide which textures can stay resident. However, if several smaller textures are used 
only slightly more frequently than, say, a much larger texture, texturing performance can 
suffer considerably. You can provide hints to whatever mechanism an implementation 
uses to decide texture residency by setting each texture’s priority with this function: 


void glPrioritizeTextures(GLsizei n, const GLuint *textures, 
const GLclampf *priorities) ; 


This function takes an array of texture object names and a corresponding array of texture 
object priorities that are clamped between 0 and 1.0. A low priority tells the implementa- 
tion that this texture object should be left out of resident memory whenever space 
becomes tight. A higher priority (such as 1.0) tells the implementation that you want that 
texture object to remain resident if possible, even if the texture seems to be used infre- 
quently. 


Summary 


In this chapter, we extended the simple image loading and display methods from the 
preceding chapter to applying images as texture maps to real three-dimensional geometry. 
You learned how to load a texture map and use texture coordinates to map the image to 
the vertices of geometry. You also learned the different ways in which texture images can 
be filtered and blended with the geometry color values and how to use mipmaps to 
improve both performance and visual fidelity. Finally, we discussed how to manage multi- 
ple textures and switch between them quickly and easily, and how to tell OpenGL which 
textures should have priority if any high-performance (or local) texture memory is avail- 
able. 


Reference 


glAreTexturesResident 


Purpose: Determine whether a set of texture objects is resident. 
Include File: <gl.h> 
Syntax: 


GLboolean glAreTexturesResident(GLsizei n, const GLuint *textures, 
GLboolean *residences) ; 


Description: Many OpenGL implementations support a high-performance set of 
textures that are said to be resident. Resident textures are kept in local or 
fast memory accessible directly by the OpenGL hardware. Texturing with 
resident textures is substantially faster than using nonresident textures. 
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This function allows you to test an array of texture object handles for 
residency. If all the texture object’s queries are resident, the function 
returns GL_TRUE. 


Parameters: 

n GLsizei: The size of the array of texture objects. 

textures GLuint*: The array containing texture object identifiers to be queried. 

residences GLboolean*: The array to be populated with corresponding flags (GL_TRUE 
or GL_FALSE) for each texture object. If all the texture objects specified in 
textures are resident, the array is not modified. 

Returns: None 

See Also: glGenTextures, glBindTexture, glDeleteTextures, 
glPrioritizeTextures 

glBindTexture 

Purpose: Binds the current texture state to the named target. 

Include File: <gl.h> 

Syntax: 


void glBindTexture(GLenum target, GLuint texture); 


Description: This function enables you to create or switch to a named texture state. 
On first use, this function creates a new texture state identified by the 
texture name, which is an unsigned integer. Subsequent calls with the 
same texture identifier select that texture state and make it current. 

Parameters: 

target GLenum: The texture target to bind to. It must be GL_TEXTURE_1D, 
GL_TEXTURE_2D, or GL_TEXTURE_3D. 

texture GLuint: The name or handle of the texture object. 

Returns: None. 

See Also: glGenTextures, glDeleteTextures, glAreTexturesResidient, 
glPrioritizeTextures, glIsTexture 

glCopyTexImage 

Purpose: Copies pixels from the color buffer into a texture. 


Include File: 


<gl.h> 
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Variations: 


void glCopyTexImage1D(GLenum target, GLint level, GLenum internalFormat, 


GLint x, GLint y, GLsizei width, GLint border); 


void glCopyTexImage2D(GLenum target, GLint level, GLenum internalFormat, 


Description: 


Parameters: 
target 


level 


internal 
Format 


x,y 
width, height 


GLint x, GLint y, GLsizei width, GLsizei height, GLint border); 


These functions define a one- or two-dimensional texture image using 
data read directly from the color buffer. If the source of a texture map is 
to be the result of a rendering operation, be sure to call g1Finish to 
ensure that OpenGL has completed the rendering operation before 
calling this function. Data is read from the color buffer specified by the 
glReadBuffer function. 


GLenum: The texture target. It must be GL_TEXTURE_1D for 
glCopyTexImage1D and GL_TEXTURE_2D for glCopyTexImage2D. 

GLint: The mipmap level to be loaded. 

GLenum: The internal format and resolution of the texture data. This must 
be one of the constants for texture formats acceptable by glTexImage, 
with the exception that you cannot use the values 1, 2, 3, or 4 for the 
number of color components. 

GLint: The location in the color buffer to begin reading color data. 


GLsizei: The width and height (for glCopyTexImage2D only) of the color 
data rectangle to be read from the color buffer. 


border GLint: The width of the texture border. Only 1 or 0 is allowed. 
Returns: None. 

See Also: glTexImage, glCopyTexSubImage 

glCopyTexSubImage 

Purpose: Replaces part of a texture map using data from the color buffer. 
Include File: <gl.h> 

Variations: 


void glCopyTexSubImage1D(GLenum target, GLint level, 


GLint xoffset, 
GLint x, GLint y, 
GLsizei width); 


Reference 


void glCopyTexSubImage2D(GLenum target, GLint level, 


GLint xoffset, GLint yoffset, 
GLint x, GLint y, 
GLsizei width, GLsizei height); 


void glCopyTexSubImage3D(GLenum target, GLint level, 


Description: 


Parameters: 
target 


level 
xoffset 
yoftfset 


zoffset 


x, Y 


width, height 


GLint xoffset, GLint yoffset, Glint zoffset, 
GLint x, GLint y, 
GLsizei width, GLsizei height); 


This function replaces part of an existing texture map with data read 
directly from the color buffer. If the source of a texture map is to be the 
result of a rendering operation, be sure to call g1Finish to ensure that 
OpenGL has completed the rendering operation before calling this func- 
tion. Data is read from the color buffer specified by the glReadBuffer 
function. 


GLenum: The texture target. It must be GL_TEXTURE_1D for 
glCopyTexSubImage1D, GL_TEXTURE_2D for glCopyTexSubImage2D, and 
GL_TEXTURE_3D for glcopyTexSubImagesD. 


GLint: The mipmap level being updated. 
GLint: The x offset into the texture map to begin replacing data. 


GLint: The y offset into the two- or three-dimensional texture map to 
begin replacing data. 

GLint: The z offset into the three-dimensional texture map to begin 
replacing data. 

GLint: The x,y location in the color buffer to begin reading the texture 
data. 


GLsizei: The width and height (for two and three dimensions only) of 
the data to be read from the color buffer. 


Returns: None. 

See Also: glTexImage, glCopyTexImage, glTexSubImage 
glDeleteTextures 

Purpose: Deletes a set of texture objects. 

Include File: <gl.h> 

Syntax: 


void glDeleteTextures(GLsizei n, const GLuint *textures) ; 
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Description: This function deletes a set of texture objects. When a texture object is 
deleted, it is available to be redefined by a subsequent call to 
glBindTexture. Any memory used by the existing texture objects is 
released and available for other textures. Any invalid texture object 
names in the array are ignored. 


Parameters: 

n GLsizei: The number of texture objects to delete. 

textures GLuint*: An array containing the list of texture objects to be deleted. 
Returns: None. 

See Also: glGenTextures, glBindTexture 

glGenTextures 

Purpose: Generates a list of texture object names. 

Include File: <gl.h> 

Syntax: 


void glGenTextures(GLsizei n, GLuint *textures); 


Description: This function fills an array with the requested number of texture objects. 
Texture object names are unsigned integers, but there is no guarantee 
that the returned array will contain a continuous sequence of integer 
names. Texture object names returned by this function are always be 
unique, unless they have been previously deleted with g1DeleteTextures. 


Parameters: 

n GLsizei: The number of texture object names to generate. 

textures GLuint*: An array containing the list of newly generated texture object 
names. 

Returns: None. 

See Also: glDeleteTextures, glBindTexture, glIsTexture 


glGetTexLevelParameter 


Purpose: Returns texture parameters for a specific mipmap level. 
Include File: <gl.h> 
Variations: 


void glGetTexLevelParameterfv(GLenum target, GLint level, GLenum pname, 
GLfloat *params) ; 


Reference 


void glGetTexLevelParameteriv(GLenum target, GLint level, GLenum pname, 


GLint *params) ; 


This function enables you to query for the value of a number of different 
parameters that may be valid for a specific texture mipmap level. Table 
8.5 lists the specific texture level parameters that may be queried. 
Returned results may be contained in one or more floating-point or 


GLenum: The texture target being queried. It must be GL_TEXTURE_1D, 
GL_TEXTURE_2D, GL_TEXTURE_3D, GL_PROXY_TEXTURE_1D, 
GL_PROXY_TEXTURE_2D, GL_PROXY_TEXTURE_3D, 
GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, 
GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, 
GL_TEXTURE_CUBE_MAP_POSITIVE_Z, or GL_TEXTURE_CUBE_MAP_NEGATIVE_Z. 


GLint: The mipmap level being queried. 
GLenum: A constant value from Table 8.5 that specifies the texture parame- 


GLfloat* or GLint*: The returned parameter value or values are stored 


Description: 
integer values. 
Parameters: 
target 
level 
pname 
ter being queried. 
params 
here. 
Returns: None. 
See Also: 


glGetTexParameter, glTexParameter 


TABLE 8.5 Texture-Level Parameter Query Constants 


Constant 


GL_TEXTURE WIDTH 


GL_TEXTURE_HEIGHT 


GL_TEXTURE_DEPTH 


GL_TEXTURE_INTERNAL_FORMAT 
GL_TEXTURE_BORDER 
GL_TEXTURE_RED_SIZE 
GL_TEXTURE_GREEN_SIZE 
GL_TEXTURE_BLUE_SIZE 
GL_TEXTURE_ALPHA_SIZE 
GL_TEXTURE_LUMINANCE_SIZE 
GL_TEXTURE_INTENSITY_SIZE 
GL_TEXTURE_COMPONENTS 
GL_TEXTURE_COMPRESSED_IMAGE_SIZE 


Description 


The width of the texture image, including the texture 
border if defined 

The height of the texture image, including the texture 
border if defined 

The depth of the texture image, including the texture 
border if defined 

The internal format of the texture image 

The width of the texture border 

The resolution in bits of the red component of a texel 
The resolution in bits of the green component of a texel 
The resolution in bits of the blue component of a texel 
The resolution in bits of the alpha component of a texel 
The resolution in bits of the luminance of a texel 

The resolution in bits of the intensity of a texel 

The number of color components in the texture image 
The size in bytes of the compressed texture image (must 
have a compressed internal format) 
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glGetTexParameter 


Purpose: 
Include File: 
Variations: 


Queries for texture parameter values. 
<gl.h> 


void glGetTexParameterfv(GLenum target, GLenum pname, GLfloat *params); 
void glGetTexParameteriv(GLenum target, GLenum pname, GLint *params); 


Description: 


Parameters: 
target 
pname 
params 


Returns: 
See Also: 


This function enables you to query for the value of a number of different 
texture parameters. This function is frequently used with one of the 
proxy texture targets to see whether a texture can be loaded. Table 8.6 
lists the specific texture parameters that may be queried. Returned results 
may be contained in one or more floating-point or integer values. 


GLenum: The texture target being queried. It must be GL_TEXTURE_1D, 
GL_TEXTURE_2D, GL_TEXTURE_3D, GL_PROXY_TEXTURE_1D, 
GL_PROXY_TEXTURE_2D, GL_PROXY_TEXTURE_3D, or GL_TEXTURE_CUBE_MAP. 


GLenum: The parameter value being queried. It may be any constant from 
Table 8.6. 


GLfloat* or GLint*: Address of variable or variables to receive the para- 
meter value or values. 


None. 
glGetTexLevelParameter, glTexParameter 


TABLE 8.6 Texture Parameter Query Constants 


Constant 


Description 


GL_TEXTURE_MAG_FILTER 
GL_TEXTURE_MIN_FILTER 
GL_TEXTURE_MIN_LOD 
GL_TEXTURE_MAX_LOD 
GL_TEXTURE_BASE_LEVEL 
GL_TEXTURE_MAX_LEVEL 
GL_TEXTURE_LOD_BIAS 
GL_TEXTURE_WRAP_S 
GL_TEXTURE_WRAP_T 
GL_TEXTURE_WRAP_R 
GL_TEXTURE_BORDER_COLOR 
GL_TEXTURE_PRIORITY 
GL_TEXTURE_RESIDENT 
GL_DEPTH_TEXTURE_MODE 
GL_TEXTURE_COMPARE_MODE 
GL_TEXTURE_COMPARE_FUNC 
GL_TEXTURE_GENERATE_MIPMAP 


Returns the texture magnification filter value 

Returns the texture minification filter 

Returns the minimum level of detail value 

Returns the maximum level of detail value 

Returns the base texture mipmap level 

Returns the maximum mipmap array level 

Texture Level of Detail bias 

Returns the wrap mode in the s coordinate direction 
Returns the wrap mode in the t coordinate direction 
Returns the wrap mode in the r coordinate direction 
Returns the texture border color 

Returns the current texture priority settings 

Returns GL_TRUE if the texture is resident, GL_FALSE otherwise 
Returns the depth texture mode 

Returns the texture comparison mode 

Returns the texture comparison function 

Returns GL_TRUE if automatic mipmap generation is enabled 


Reference 


glGetTexImage 

Purpose: Returns a texture image. 
Include File: <gl.h> 

Syntax: 


void glGetTexImage(GLenum target, GLint level, GLenum format, 
GLenum type, void *pixels); 


Description: This function enables you to fill a data buffer with the data that 
comprises the current texture. This function performs the reverse opera- 
tion of gl1TexImage, which loads a texture with a supplied data buffer. 


Parameters: 

target GLenum: The texture target to be copied. It must be GL_TEXTURE_1D, 
GL_TEXTURE_2D, GL_TEXTURE_3D, GL_TEXTURE_CUBE_MAP_POSITIVE_X, 
GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y, 
GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, or 
GL_TEXTURE_CUBE_MAP_NEGATIVE_Z. 

level GLint: The mipmap level to be read. 

format GLenum: The desired pixel format of the returned data. It may be GL_RED, 
GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, GL_BGR, 
GL_BGRA, or GL_LUMINANCE_ALPHA. 

type GLenum: The pixel type for the returned data. It may be any pixel type 
listed in Table 8.3. 

pixels void*: Pointer to a memory buffer to accept the texture image. 

Returns: None. 

See Also: glTexImage 

glisTexture 

Purpose: Determines whether a texture object name is valid. 


Include File: <gl.h> 
Syntax: 
GLboolean glIsTexture(GLuint texture) ; 


Description: This function enables you to determine whether a given integer value is a 
valid texture object name. A valid texture object is an integer name that 
is in use. This means that g1BindTexture has been used to bind to this 
texture object name at least once, and it has not been subsequently 
deleted with g1DeleteTextures. 
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Parameters: 
texture 


Returns: 


See Also: 


GLuint: The texture object in question. 


GL_TRUE if the texture object is a valid (in-use) texture object name; 
GL_FALSE otherwise. 


glGenTextures, glDeleteTextures, glBindTexture, 
glAreTexturesResidient, glPrioritizeTextures 


glPrioritizeTextures 


Purpose: 
Include File: 
Syntax: 


Sets priority of a texture object. 
<gl.h> 


void glPrioritizeTextures(GLsizei n, Gluint *textures, 


Description: 


Parameters: 
n 


textures 
priorities 


Returns: 
See Also: 


glTexCoord 


Purpose: 


Include File: 


const GLclampf *priorities); 


This function assigns n priorities to the texture objects contained in the 
textures array. The array of priorities is specified in priorities. A 
texture priority is a clamped value between 0.0 and 1.0 that provides the 
implementation with a hint that the given texture should remain resi- 
dent. Resident textures are textures that are stored in high performance 
or local memory. A texture priority of 1.0 signifies a strong hint to keep 
the texture resident, whereas 0.0 signifies that the texture may be 
swapped out if necessary. 


GLsizei: The number of texture object names contained in the textures 
array. 


GLuint*: An array of texture object names. Each array element corre- 
sponds to a priority to be set in the priorities array. 


const GLclampf*: An array of clamped floating-point values that specify 
a texture object’s priority. The array element corresponds to a particular 
texture object name in the same location in the textures array. 


None. 


glAreTexturesResident, glGenTextures, glBindTexture, 
glDeleteTexture, glIsTexture 


Specifies the current texture image coordinate for textured polygon 
rendering. 


<gl.h> 


Reference 


Variations: 


void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 


glTexCoordif(GLfloat s); 

glTexCoord1fv(GLfloat *v); 

glTexCoordid(GLdouble s); 

glTexCoordidv(GLdouble *v); 

glTexCoord1i(GLint s); 

glTexCoordtiv(GLint *v); 

glTexCoordis(GLshort s); 

glTexCoordisv(GLfloat *v); 

glTexCoord2f(GLfloat s, GLfloat t); 
glTexCoord2fv(GLfloat *v); 

glTexCoord2d(GLdouble s, GlLdouble t); 
glTexCoord2dv(GLdouble *v); 

glTexCoord2i(GLint s, GLint t); 
glTexCoord2iv(GLint *v); 

glTexCoord2s(GLshort s, GLshort t); 
glTexCoord2sv(GLfloat *v); 

glTexCoord3f(GLfloat s, GLfloat t, GLfloat r); 
glTexCoord3fv(GLfloat *v); 

glTexCoord3d(GLdouble s, GlLdouble t, GLdouble r); 
glTexCoord3dv(GLdouble *v); 

glTexCoord3i(GLint s, GLint t, GLint r); 
glTexCoord3iv(GLint *v); 

glTexCoord3s(GLshort s, GLshort t, GLshort r); 
glTexCoord3sv(GLfloat *v); 

glTexCoord4f (GLfloat s, GLfloat t, GLfloat r, GLfloat q); 
glTexCoord4fv(GLfloat *v); 

glTexCoord4d(GLdouble s, GLdouble t, GLdouble r, GLdouble q); 
glTexCoord4dv(GLdouble *v); 

glTexCoord4i(GLint s, GLint t, GLint r, Glint q); 
glTexCoord4iv(GLint *v); 

glTexCoord4s(GLshort s, GLshort t, GLshort r, GLshort q); 
glTexCoord4sv(GLfloat *v); 


Description: These functions set the current texture image coordinate in one to four 


dimensions. Texture coordinates can be updated anytime between 
glBegin and glEnd, and correspond to the following glVertex call. The 
texture g coordinate is used to scale the s, t, and r coordinate values and 
by default is 1.0. You can perform any valid matrix operation on texture 
coordinates by specifying GL_TEXTURE as the target of g1MatrixMode. 
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Parameters: 


s 


Returns: 
See Also: 


glTexEnv 


Purpose: 
Include File: 
Variations: 


GLdouble or GLfloat or GLint or GLshort: The horizontal texture image 
coordinate. 


GLdouble or GLfloat or GLint or GLshort: The vertical texture image 
coordinate. 


GLdouble or GLfloat or GLint or GLshort: The texture image depth coor- 
dinate. 


GLdouble or GLfloat or GLint or GLshort: The texture image scaling value 
coordinate. 


GLdouble* or GLfloat* or GLint* or GLshort*: An array of values that 
contain the one, two, three, or four values needed to specify the texture 
coordinate. 


None. 
glTexGen, glTexImage, glTexParameter 


Sets the texture environment parameters. 
<gl.h> 


void glTexEnvf(GLenum target, GLenum pname, GLfloat param) ; 
void glTexEnvfv(GLenum target, GLenum pname, GLfloat *param); 
void glTexEnvi(GLenum target, GLenum pname, GLint param); 
void glTexEnviv(GLenum target, GLenum pname, GLint *param); 


Description: 


Parameters: 
target 


pname 


These functions set texture mapping environment parameters. The 
texture environment is set per texture unit and exists outside the state 
bound by glBindTexture. Thus, all texture objects that can be bound to 
an active texture unit are influenced by the texture environment. 


GLenum: The texture environment to define. It must be GL_TEXTURE_ENV or 
GL_TEXTURE_FILTER_CONTROL. 


GLenum: The parameter name to define. 


When the target is GL_TEXTURE_FILTER CONTROL, the parameter name 
must be GL_TEXTURE_LOD_BIAS, and the parameter is the value that biases 
the mipmap level of the detail selection. 


When the target is G__TEXTURE_ENV, the parameter name may be 
GL_TEXTURE_ENV_MODE, GL_TEXTURE_ENV_COLOR, GL_COMBINE_RGB, or 
GL_COMBINE_ALPHA. 


Reference 


When the parameter name is GL_TEXTURE_ENV_COLOR, the parameter 
points to an array containing the color values of the texture environment 
color. 
When the parameter name is GL_TEXTURE_ENV_MODE, the valid parameters 
are GL_REPLACE, GL_DECAL, GL_MODULATE, GL_BLEND, GL_ADD, or GL_COMBINE. 
These environment modes are described in Table 8.7. 

param The parameter value. It must be one of the values above (GL_REPLACE, 
GL_DECAL, GL_MODULATE, GL_BLEND, GL_ADD, or GL_COMBINE), or for 
GL_TEXTURE_ENV_COLOR, an array containing the RGBA color components 
of the texture environment color. 

Returns: None. 


See Also: glTexParameter 


TABLE 8.7. Texture Environment Modes 
Constant Description 


GL_DECAL Texel values are applied to geometry fragment values. If blending is enabled and 
the texture contains an alpha channel, the geometry blends through the texture 
according to the current blend function. 

GL_REPLACE Texel values replace geometry fragment values. If blending is enabled and the 
texture contains an alpha channel, the texture’s alpha values are used to replace 
the geometry fragment colors in the color buffer. 


GL_MODULATE Texel color values are multiplied by the geometry fragment color values. 
GL_ADD Texel color values are added to the geometry color values. 

GL_BLEND Texel color values are multiplied by the texture environment color. 
GL_COMBINE Texel color values are combined with a second texture unit according to the 


texture combine function (see the next chapter). 


glTexImage 

Purpose: Defines a one-, two-, or three-dimensional texture image. 
Include File: <gl.h> 

Variations: 


void glTexImage1D(GLenum target, GLint level, GLint internalformat, 
GLsizei width, GLint border, 
GLenum format, GLenum type, void *data); 


void glTexImage2D(GLenum target, GLint level, GLint internalformat, 
GLsizei width, GLsizei height, GLint border, 
GLenum format, GLenum type, void *data); 
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void glTexImage3D(GLenum target, GLint level, GLint internalformat, 
GLsizei width, GLsizei height, GLsizei depth, GLint border, 
GLenum format, GLenum type, void *data); 


Description: This function defines a one-, two-, or three-dimensional texture image. 
The image data is subject to modes defined with g1PixelMap, 
glPixelStore, and glPixelTransfer. 


Parameters: 


target GLenum: The texture target being specified. Must be GL_TEXTURE_1D or 
GL_PROXY_TEXTURE_1D for glTexImage1D, GL_TEXTURE_2D or 
GL_PROXY_TEXTURE_2D for glTexImage3D, GL_TEXTURE_3D or 
GL_TEXTURE_PROXY_3D for g1TexImage3D. For 2D cube maps only, it may 
also be GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGA- 
TIVE_X, GL_CUBE_MAP_POSITIVE_Y, GL_CUBE_MAP_NEGATIVE_Y, 
GL_CUBE_MAP_POSITIVE_Z, or GL_CUBE_MAP_NEGATIVE_Z. 


level GLint: The level of detail. Usually, 0 unless mipmapping”is used. 


internalFormat GLint: The internal format of the image data. It may contain the 
numbers 1-4 to specify the number of color components, or one of the 
following constants: GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, 
GL_ALPHA16, GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMI - 
NANCE12, GL_LUMINANCE16, GL_LUMINANCE_ALPHA, GL_LUMINANCE4_ALPHA4, 
GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4, 
GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_INTENSITY, 
GL_INTENSITY4, GL_INTENSITY8, GL_INTENSTIY12, GL_INTENSITY16, 
GL_RGB, GL_R3_G3_B2, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12, 
GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8, 
GL_RGB10_A2, GL_RGBA12, GL_RGBA16. 


width GLsizei: The width of the one-, two-, or three-dimensional texture 
image. This must be a power of 2 but may include a border. 


height GLsizei: The height of the two- or three-dimensional texture image. This 
must be a power of 2 but may include a border. 

depth GLsizei: The depth of a three-dimensional texture image. This must be a 
power of 2 but may include a border. 

border GLint: The width of the border. All implementations must support 0, 1, 
and 2 texel borders. 

format GLenum: The format of the pixel data. Any texel format type from Table 
8.2 is valid. 

type GLenum: The data type of each texel value. Any data type from Table 8.3 is 
valid. 


pixels GLvoid *: The pixel data. 


Reference 


Returns: None. 

See Also: glTexSubImage, glCopyTexImage, glCopyTexSubImage 
glTexParameter 

Purpose: Sets texture mapping parameters. 

Include File: <gl.h> 

Variations: 


void glTexParameterf(GLenum target, GLenum pname, GLfloat param); 
void glTexParameterfv(GLenum target, GLenum pname, GLfloat *param) ; 
void glTexParameteri(GLenum target, GLenum pname, GLint param); 
void glTexParameteriv(GLenum target, GLenum pname, GLint *param) ; 


Description: This function sets several texture mapping parameters. These parameters 
are bound to the current texture state that can be made current with 
glBindTexture. 

Parameters: 

target GLenum: The texture target for which this parameter applies. Must be one 


of GL_TEXTURE_1D, GL_TEXTURE_2D, GL_TEXTURE_3D, or 
GL_TEXTURE_CUBE_MAP. 


pname GLenum: The texturing parameter to set. Valid names are as follows: 


GL_TEXTURE_MIN_FILTER: Specifies the texture image minification (reduc- 
tion) method or filter. Any texture filter from Table 8.4 may be used. 


GL_TEXTURE_MAX_FILTER: Specifies the texture image magnification 
(enlargement) method or filter. Any texture filter from Table 8.4 may be 
used. 

GL_TEXTURE_MAX_LOD: Specifies the maximum texture LOD to be used for 
mipmapping. 

GL_TEXTURE_MIN_LOD: Specifies the minimum texture LOD to be used for 
mipmapping. 

GL_TEXTURE_BASE_LEVEL: Specifies the minimum texture LOD to be 
loaded. 


GL_TEXTURE_MAX_LEVEL: Specifies the maximum texture LOD to be 
loaded. 


GL_TEXTURE_WRAP_S: Specifies handling of texture s coordinates outside 
the range of 0.0 to 1.0 (GL_CLAMP, GL_CLAMP_TO_EDGE, 
GL_CLAMP_TO_BORDER, GL_REPEAT, GL_MIRRORED_REPEAT). 
GL_TEXTURE_WRAP_T: Specifies handling of texture t coordinates outside 
the range of 0.0 to 1.0 (GL_CLAMP, GL_CLAMP_TO_EDGE, 
GL_CLAMP_TO_BORDER, GL_REPEAT, GL_MIRRORED_REPEAT). 
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GL_TEXTURE_WRAP_R: Specifies handling of texture r coordinates outside 
the range of 0.0 to 1.0 (GL_CLAMP, GL_CLAMP_TO_EDGE, 
GL_CLAMP_TO_BORDER, GL_REPEAT). 

GL_BORDER_COLOR: Specifies a border color for textures without borders. 
GL_GENERATE_MIPMAP: Specifies whether mipmap LODs should be auto- 
matically built (GL_TRUE = yes). 


GL_TEXTURE_PRIORITY: Sets the texture priority for this texture. It must be 


a clamped value in the range 0.0 to 1.0. 

GL_DEPTH_TEXTURE_MODE: Sets the depth texture mode (see Chapter 18). 
GL_TEXTURE_COMPARE_MODE: Sets the texture comparison mode (see 
Chapter 18). 


GL_TEXTURE_COMPARE_FUNC: Sets the texture comparison function (see 
Chapter 18). 


param GLfloat or GLfloat* or GLint or GLint*: Value of the parameter specified 
by pname. 

Returns: None. 

See Also: glTexEnv, glTexGen, glBindTexture 

glTexSubImage 

Purpose: Replaces a portion of an existing texture map. 


Include File: <gl.h> 
Variations: 


void glTexSubImage1D(GLenum target, GLint level, 
GLint xOffset, 
GLsizei width, 
GLenum format, GLenum type, const GLvoid *data); 


void glTexSubImage2D(GLenum target, GLint level, 
GLint xOffset, GLint yOffset, 
GLsizei width, GLsizei height, 
GLenum format, GLenum type, const GLvoid *data); 


void glTexSubImage3D(GLenum target, GLint level, 
GLint xOffset, GLint yOffset, GLint zOffset, 
GLsizei width, GLsizei height, GlLsizei depth, 
GLenum format, GLenum type, const GLvoid *data); 


Description: 


Parameters: 


target 


level 
xOffset 


yOffset 


zOffset 


width 


height 


depth 
format 
type 
data 


Returns: 


See Also: 


Reference 431 


This function replaces a portion of an existing one-, two-, or three- 
dimensional texture map. Updating all or part of an existing texture map 
may be considerably faster than reloading a texture image with 
glTexImage. You cannot perform an initial texture load with this func- 
tion; it is used only to update an existing texture. 


GLenum: The texture target. Must be GL_TEXTURE_1D, GL_TEXTURE_2D, or 
GL_TEXTURE_3D. 


GLint: Mipmap level to be updated. 


GLint: Offset within the existing one-, two-, or three-dimensional texture 
in the x direction to begin the update. 


GLint: Offset within the existing two- or three-dimensional texture in the 
y direction to begin the update. 


GLint: Offset within the existing three-dimensional texture in the z direc- 
tion to begin the update. 


GLsizei: The width of the one-, two-, or three-dimensional texture data 
being updated. 


GLsizei: The height of the two- or three-dimensional texture data being 
updated. 


GLsizei: The depth of the three-dimensional texture data being updated. 
GLenum: Any valid texture format. See Table 8.2. 
GLenum: Any valid pixel data type. See Table 8.3. 


const void*: Pointer to the data that is being used to update the texture 
target. 


None. 
glTexImage, glCopyTexSubImage 


gluBuildMipmapLevels 


Purpose: 


Include File: 


Variations: 


Automatically generates and updates a range of mipmap levels. 
<gl.h> 


int gluBuildiDMipmapLevels(GLenum target, GLint internalFormat, 


GLint width, 
GLenum format, GLenum type, GLint level, 
GLint base, GLint max, const void *data); 


int gluBuild2DMipmapLevels(GLenum target, GLint internalFormat, 


GLint width, GLint height, 


432 


CHAPTER 8 Texture Mapping: The Basics 


GLenum format, GLenum type, GLint level, 
GLint base, GLint max, const void *data); 


int gluBuild3DMipmapLevels(GLenum target, Glint internalFormat, 


GLint width, GLint height, GLint depth, 
GLenum format, GLenum type, GLint level, 
GLint base, GLint max, const void *data); 


Description: This function uses gluScaleImage to automatically scale and load a series 
of mipmap levels based on an initial level provided. The advantage to 
using this function is that it allows only a selected range of mip levels to 
be updated. 

Parameters: 

target GLenum: The texture target. Must be GL_TEXTURE_1D, GL_TEXTURE_2D, or 
GL_TEXTURE_3D. 

internal GLint: Any valid texture internal format recognized by glTexImage. 

Format 

width GLint: The width of the one-, two-, or three-dimensional texture source. 

height GLint: The height of the two- or three-dimensional texture source. 

depth GLint: The depth of the three-dimensional texture source. 

format GLenum: Any valid texel format. See Table 8.2. 

type GLenum: Any valid texel data type. See Table 8.3. 

level GLint: The base mipmap level being specified by the data in data. 

base GLint: The starting mip level to begin mipmap generation. 

max GLint: The highest mip level (smallest image) to generate. 

data void*: The supplied texture image data. 

Returns: None. 

See Also: gluBuildMipmaps 

gluBuildMipmaps 

Purpose: Automatically creates and loads a set of complete mipmaps. 


Include File: 


Variations: 


<gl.h> 


int gluBuildiDMipmaps(GLenum target, GLint internalFormat, 


GLint width, 
GLenum format, GLenum type, const void *data); 


Reference 


int gluBuild2DMipmaps(GLenum target, GLint internalFormat, 


GLint width, GLint height, 
GLenum format, GLenum type, const void *data); 


int gluBuild3DMipmaps(GLenum target, GLint internalFormat, 


Description: 


Parameters: 
target 


internalFormat 
width 

height 

depth 

format 

type 

data 

Returns: 


See Also: 


GLint width, GLint height, GLint depth, 
GLenum format, GLenum type, const void *data); 


This function takes the texture data given for the base mipmapped 
texture level and automatically scales the image repeatedly and loads 
each mip level in turn. This work is done by the client CPU and not by 
the OpenGL implementation, and thus may be a time-consuming 
operation: 


GLenum: The texture target. Must be GL_TEXTURE_1D, GL_TEXTURE_2D, or 
GL_TEXTURE_3D. 


GLint: Any valid texture internal format recognized by glTexImage. 
GLint: The width of the one-, two-, or three-dimensional texture source. 
GLint: The height of the two- or three-dimensional texture source. 
GLint: The depth of the three-dimensional texture source. 

GLenum: Any valid texel format. See Table 8.2. 

GLenum: Any valid texel data type. See Table 8.3. 

void*: The base mipmap level texture data. 

None: 


gluBuildMipmapLevels 
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CHAPTER 9 


Texture Mapping: Beyond the Basics 


by Richard S. Wright, Jr. 


WHAT YOU'LL LEARN IN THIS CHAPTER: 


How To Functions You'll Use 


Add specular highlights to textured objects glLightModel, glSecondaryColor 
Use anisotropic texture filtering glTexParameterf 
Load and use compressed textures glCompressedTexImage, glCompressedTexSubImage 


Texture mapping is perhaps one of the most exciting features of OpenGL (well, close 
behind shaders anyway!) and is heavily relied on in the games and simulation industry. In 
Chapter 8, “Texture Mapping: The Basics,” you learned the basics of loading and applying 
texture maps to geometry. In this chapter, we expand on this knowledge and cover some 
of the finer points of texture mapping in OpenGL. 


Secondary Color 


Applying to geometry, in regards to how lighting works, causes a hidden and often unde- 
sirable side effect. In general, you set the texture environment to GL_MODLULATE, causing lit 
geometry to be combined with the texture map in such a way that the textured geometry 
also appears lit. Normally, OpenGL performs lighting calculations and calculates the color 
of individual fragments according to the standard light model. These fragment colors are 
then combined with the filtered texels being applied to the geometry. However, this 
process has the side effect of greatly reducing the visibility of specular highlights on the 
geometry. 


For example, Figure 9.1 shows the original lit SPHEREWORLD sample from Chapter 5, 
“Color, Materials, and Lighting: The Basics.” In this figure, you can see clearly the specular 
highlights reflecting off the surface of the torus. In contrast, Figure 9.2 shows the SPHERE- 
WORLD sample from the preceding chapter. In this figure, you can see the effects of 
having the texture applied after the lighting has been added. 
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TOpencl SphereWorld Demo + Lights and Shadow 


FIGURE 9.1. Original SPHEREWORLD torus with specular highlights. 


FIGURE 9.2 Textured torus with muted highlights. 


Secondary Color 


The solution to this problem is to apply the specular highlights after texturing. This tech- 
nique, called the secondary specular color, can be applied manually or automatically calcu- 
lated by the lighting model. Usually, you do this using the normal OpenGL lighting model 
and simply turn it on using glLightModel, as shown here: 


glLightModeli(GL_LIGHT _MODEL_COLOR CONTROL, GL_SEPARATE_SPECULAR_COLOR) ; 

You can switch back to the normal lighting model by specifying GL_SINGLE_COLOR for the 
light model parameter: 

glLightModeli(GL_LIGHT_MODEL_COLOR_CONTROL, GL_COLOR_SINGLE) ; 

Figure 9.3 shows the output from this chapter’s version of SPHEREWORLD with the 


restored specular highlights on the torus. We do not provide a listing for this sample 
because it simply contains the addition of the preceding single line of code. 


FIGURE 9.3 Highlights restored to textured torus. 


You can also directly specify a secondary color after texturing when you are not using 
lighting (lighting is disabled) using the gl1SecondaryColor function. This function comes 
in many variations just as glColor does and is fully documented in the reference section. 
You should also note that if you specify a secondary color, you must also explicitly enable 
the use of the secondary color by enabling the GL_COLOR_SUM flag: 


glEnable(GL_COLOR_SUM) ; 
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Anisotropic Filtering 


Anisotropic texture filtering is not a part of the core OpenGL specification, but it is a 
widely supported extension that can dramatically improve the quality of texture filtering 
operations. Texture filtering was covered in the preceding chapter, where you learned 
about the two basic texture filters: nearest neighbor (GL_NEAREST) and linear (GL_LINEAR). 
When a texture map is filtered, OpenGL uses the texture coordinates to figure out where 
in the texture map a particular fragment of geometry falls. The texels immediately around 
that position are then sampled using either the GL_NEAREST or GL_LINEAR filtering opera- 
tions. 


This process works perfectly when the geometry being textured is viewed directly perpen- 
dicular to the viewpoint, as shown to the left in Figure 9.4. However, when the geometry 
is viewed from an angle more oblique to the point of view, a regular sampling of the 
surrounding texels results in the loss of some information in the texture (it looks blurry!). 
A more realistic and accurate sample would be elongated along the direction of the plane 
containing the texture. This result is shown to the right in Figure 9.4. Taking this viewing 
angle into account for texture filtering is called anisotropic filtering. 


Isotropic sampling Anisotropic sampling 


FIGURE 9.4 Normal texture sampling versus anisotropic sampling. 


You can apply anisotropic filtering to any of the basic or mipmapped texture filtering 
modes; applying it requires three steps. First, you must determine whether the extension is 
supported. You can do this by querying for the extension string 
GL_EXT_texture_filter_anisotropic. You can use the glTools function named 
gltIsExtensionSupported for this task: 


if (gltIsExtSupported("GL_EXT_texture_filter_anisotropic") ) 
// Set Flag that extension is supported 


After you determine that this extension is supported, you can find the maximum amount 
of anisotropy supported. You can query for it using g1GetFloatv and the parameter 
GL_MAX_TEXTURE_MAX_ANISOTROPY_EXT: 


GLfloat fLargest; 


glGetFloatv(GL_MAX_TEXTURE_MAX_ANISOTROPY_EXT, &fLargest); 
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The larger the amount of anisotropy applied, the more texels are sampled along the direc- 
tion of greatest change (along the strongest point of view). A value of 1.0 represents 
normal texture filtering (called isotropic filtering). Bear in mind that anisotropic filtering is 
not free. The extra amount of work, including other texels, can sometimes result in 
substantial performance penalties. On modern hardware, this feature is getting quite fast 
and is becoming a standard feature of popular games, animation, and simulation 
programs. 


Finally, you set the amount of anisotropy you want applied using g1TexParameter and the 
constant GL_TEXTURE_MAX_ANISOTROPY_EXT. For example, using the preceding code, if you 
want the maximum amount of anisotropy applied, you would call g1TexParameter as 
follows: 


glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_MAX_ANISOTROPY_EXT, fLargest); 


This modifier is applied per texture object just like the standard filtering parameters. 


The sample program ANISOTROPIC provides a striking example of anisotropic texture 
filtering in action. This program displays a tunnel with walls, a floor, and ceiling geome- 
try. The arrow keys move your point of view (or the tunnel) back and forth along the 
tunnel interior. A right mouse click brings up a menu that allows you to select from 

the various texture filters, and turn on and off anisotropic filtering. Figure 9.5 shows the 
tunnel using trilinear filtered mipmapping. Notice how blurred the patterns become in 
the distance, particularly with the bricks. 


FIGURE 9.5 ANISOTROPIC tunnel sample with trilinear filtering. 
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Now compare Figure 9.5 with Figure 9.6, where anisotropic filtering has been enabled. The 
mortar between the bricks is now clearly visible all the way to the end of the tunnel. In 
fact, anisotropic filtering can also greatly reduce the visible mipmap transition patterns for 
the GL_LINEAR_MIPMAP_NEAREST and GL_NEAREST_MIPMAP_NEAREST mipmapped filters. 


FIGURE 9.6 ANISOTROPIC tunnel sample with anisotropic filtering. 


Texture Compression 


Texture mapping can add incredible realism to any 3D rendered scene, with a minimal 
cost in vertex processing. One drawback to using textures, however, is that they require a 
lot of memory to store and process. Early attempts at texture compression were crudely 
storing textures as JPG files and decompressing the textures when loaded before calling 
glTexImage. These attempts saved disk space or reduced the amount of time required to 
transmit the image over the network (such as the Internet), but did little to alleviate the 
storage requirements of texture images loaded into graphics hardware memory. 


Native support for texture compression was added to OpenGL with version 1.3. Earlier 
versions of OpenGL may also support texture compression via extension functions of the 
same name. You can test for this extension by using the GL_ARB_texture_compression 
string. 
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Texture compression support in OpenGL hardware can go beyond simply allowing you to 
load a compressed texture; in most implementations, the texture data stays compressed 
even in the graphics hardware memory. This allows you to load more texture into less 
memory and can significantly improve texturing performance due to fewer texture swaps 
(moving textures around) and fewer memory accesses during texture filtering. 


Compressing Textures 

Texture data does not have to be initially compressed to take advantage of OpenGL 
support for compressed textures. You can request that OpenGL compress a texture image 
when loaded by using one of the values in Table 9.1 for the internalFormat parameter of 
any of the glTexImage functions. 


TABLE 9.1 Compressed Texture Formats 


Compressed Format Base Internal Format 
GL_COMPRESSED_ALPHA GL_ALPHA 
GL_COMPRESSED_LUMINANCE GL_LUMINANCE 
GL_COMPRESSED_LUMINANCE_ALPHA GL_LUMINANCE_ALPHA 
GL_COMPRESSED_INTENSITY GL_INTENSITY 
GL_COMPRESSED_RGB GL_RGB 
GL_COMPRESSED_RGBA GL_RGBA 


Compressing images this way adds a bit of overhead to texture loads but can increase 
texture performance due to the more efficient usage of texture memory. If, for some 
reason, the texture cannot be compressed, OpenGL uses the base internal format listed 
instead and loads the texture uncompressed. 


When you attempt to load and compress a texture in this way, you can find out whether 
the texture was successfully compressed by using glGetTexLevelParameteriv with 
GL_TEXTURE_COMPRESSED as the parameter name: 


GLint compFlag; 
glGetTexLevelParameteriv(GL_TEXTURE_2D, ®@, GL_TEXTURE_COMPRESSED, &compFlag) ; 


The glGetTexLevelParameteriv function accepts a number of new parameter names 
pertaining to compressed textures. These parameters are listed in Table 9.2. 


TABLE 9.2 Compressed Texture Parameters Retrieved with gl1GetTexLevelParameter 
Parameter Returns 
GL_TEXTURE_COMPRESSED The value 1 if the texture is compressed, 0 if not 


GL_TEXTURE_COMPRESSED_IMAGE_SIZE The size in bytes of the compressed texture 
GL_TEXTURE_INTERNAL_FORMAT The compression format used 
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TABLE 9.2. Continued 


Parameter Returns 


GL_NUM_COMPRESSED_TEXTURE_FORMATS ~— The number of supported compressed texture formats 


GL_COMPRESSED_TEXTURE_FORMATS An array of constant values corresponding to each 
supported compressed texture format 
GL_TEXTURE_COMPRESSION_HINT The value of the texture compression hint 


(GL_NICEST/GL_FASTEST) 


When textures are compressed using the values listed in Table 9.1, OpenGL chooses the 
most appropriate texture compression format. You can use glHint to specify whether you 
want OpenGL to choose based on the fastest or highest quality algorithm: 


glHint (GL_TEXTURE_COMPRESSION HINT, GL_FASTEST); 
glHint (GL_TEXTURE_COMPRESSION_HINT, GL_NICEST) ; 
glHint (GL_TEXTURE_COMPRESSION HINT, GL_DONT_CARE); 


The exact compression format varies from implementation to implementation. You can 
obtain a count of compression formats and a list of the values by using 
GL_NUM_COMPRESSED_TEXTURE_FORMATS and GL_COMPRESSED_TEXTURE_FORMATS. To check for 
support for a specific set of compressed texture formats, you need to check for a specific 
extension for those formats. For example, one of the most popular (on both PC and Mac) 
is the GL_EXT_texture_compression_s3tc texture compression format. If this extension is 
supported, the compressed texture formats listed in Table 9.3 are all supported (these 
constants are defined in glext.h), but only for two-dimensional textures. 


TABLE 9.3 Compression Formats for GL_EXT_texture_compression_s3tc 


Format , Description 

GL_COMPRESSED_RGB_S3TC_DXT1 RGB data is compressed; alpha is always 1.0. 

GL_COMPRESSED_RGBA_S3TC_DXT1 RGB data is compressed; alpha is either 1.0 or 0.0. 

GL_COMPRESSED_RGBA_S3TC_DXT3 RGB data is compressed; alpha is stored as 4 bits. 

GL_COMPRESSED_RGBA_S3TC_DXT5 RGB data is compressed; alpha is a weighted average of 8- 
bit values. 


Loading Compressed Textures 

Using the functions in the preceding section, you can have OpenGL compress textures in 
a natively supported format, retrieve the compressed data with the 
glGetCompressedTexImage function (identical to the gl1GetTexImage function in the 
preceding chapter), and save it to disk. On subsequent loads, the raw compressed data can 
be used, resulting in substantially faster texture loads. 


Texture Coordinate Generation 


To load precompressed texture data, use one of the following functions: 


void glCompressedTexImage1D(GLenum target, GLint level, GLenum internalFormat, 
GLsizei width, 
GLint border, GLsizei imageSize, void *data); 

void glCompressedTexImage2D(GLenum target, GLint level, GLenum internalFormat, 
GLsizei width, GLsizei height, 
GLint border, GLsizei imageSize, void *data); 

void glCompressedTexImage3D(GLenum target, GLint level, GLenum internalFormat, 
GLsizei width, GLsizei height, GLsizei depth, 
GLint border, Glsizei imageSize, GLvoid *data); 


These functions are virtually identical to the gl1TexImage functions from the preceding 
chapter. The only difference is that the internalFormat parameter must specify a 
supported compressed texture image. If the implementation supports the 
GL_EXT_texture_compression_s3tc extension, this would be one of the values from Table 
9.3. There is also a corresponding set of glCompressedTexSubImage functions for updating 
a portion or all of an already-loaded texture that mirrors the g1TexSubImage functionality 
from the preceding chapter. 


Texture Coordinate Generation 


In Chapter 8, you learned that textures are mapped to geometry using texture coordinates. 
Often, when you are loading models (see Chapter 11, “It’s All About the Pipeline: Faster 
Geometry Throughput”), texture coordinates are provided for you. If necessary, you can 
easily map texture coordinates manually to some surfaces such as spheres or flat planes. 
Sometimes, however, you may have a complex surface for which it is not so easy to manu- 
ally derive the coordinates. OpenGL can automatically generate texture coordinates for 
you within certain limitations. 


Texture coordinate generation is enabled on the S, T, R, and Q texture coordinates using 
glEnable: 


glEnable(GL_TEXTURE_GEN_S); 
glEnable(GL_TEXTURE_GEN_T); 
glEnable(GL_TEXTURE_GEN_R); 
glEnable(GL_TEXTURE_GEN_Q); 


When texture coordinate generation is enabled, any calls to g1TexCoord are ignored, and 
OpenGL calculates the texture coordinates for each vertex for you. In the same manner 
that texture coordinate generation is turned on, you turn it off by using g1Disable: 


glDisable(GL_TEXTURE_GEN_S); 
glDisable(GL_TEXTURE_GEN_T); 
glDisable(GL_TEXTURE_GEN_R); 
glDisable(GL_TEXTURE_GEN_Q); 
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You set the function or method used to generate texture coordinates with the following 
functions: 


void glTexGenf(GLenum coord, GLenum pname, GLfloat param); 
void glTexGenfv(GLenum coord, GLenum pname, GLfloat *param); 


The first parameter, coord, specifies which texture coordinate this function sets. It must be 
either GL_S, GL_T, GL_R, or GL_Q. The second parameter, pname, must be either 
GL_TEXTURE_GEN_MODE, GL_OBJECT_PLANE, or GL_EYE_PLANE. The last parameter sets the 
values of the texture generation function or mode. Note that integer (GLint) and double 
(GLdouble) versions of these functions are also used. 


The sample program TEXGEN is presented in Listing 9.1. This program displays a torus 
that can be manipulated (rotated around) using the arrow keys. A right-click brings up a 
context menu that allows you to select from the first three texture generation modes we 
will discuss: Object Linear, Eye Linear, and Sphere Mapping. 


LISTING 9.1 Source Code for the TEXGEN Sample Program 


$$ 


#include "../../Common/OpenGLSB.h" // System and OpenGL Stuff 
#include "../../Common/gltools.h" // gltools library 


// Rotation amounts 


static GLfloat xRot = 0.0f; 

static GLfloat yRot = 0.0f; 

GLuint toTextures[2]; // Two texture objects 

int iRenderMode = 3; // Sphere Mapped is default 


FTLTTTTTT TTT TT TTA TAL AT 
// Reset flags as appropriate in response to menu selections 
void ProcessMenu(int value) 

{ 

// Projection plane 

GLfloat zPlane[] = { 0.0f, 0.0f, 1.0f, 0.O0f }; 


// Store render mode 
iRenderMode = value; 


// Set up textgen based on menu selection 
switch(value) 
{ 
case 1: 
// Object Linear 


LISTING 9.1 Continued 


Texture Coordinate Generation 


glTexGeni(GL_S, GL_TEXTURE_GEN MODE, GL_OBJECT_LINEAR); 
glTexGeni(GL_T, GL_TEXTURE_GEN MODE, GL_OBJECT_LINEAR); 


glTexGenfv(GL_S, GL_OBJECT_PLANE, zPlane); 
glTexGenfv(GL_T, GL_OBJECT_PLANE, zPlane); 
break; 


case 2: 


// Eye Linear 

glTexGeni(GL_S, GL_TEXTURE_GEN MODE, GL_EYE_LINEAR) ; 
glTexGeni(GL_T, GL_TEXTURE_GEN_MODE, GL_EYE_LINEAR); 
glTexGenfv(GL_S, GL_EYE_PLANE, zPlane); 
glTexGenfv(GL_T, GL_EYE_PLANE, zPlane); 

break; 


case 3: 
default: 


} 


// Sphere Map 

glTexGeni(GL_S, GL_TEXTURE_GEN MODE, GL_SPHERE_MAP); 
glTexGeni(GL_T, GL_TEXTURE_GEN_MODE, GL_SPHERE_MAP) ; 
break; 


glutPostRedisplay(); // Redisplay 


} 


FETITTTTATT TTT TTT TTT TTT A ATA TAT AL 


// Called to draw scene 
void RenderScene(void) 


{ 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


// Switch to orthographic view for background drawing 
glMatrixMode(GL_PROJECTION) ; 

glPushMatrix(); 

glLoadidentity(); 

gluOrtho2D(0.0f, 1.0f, 0.0f, 1.0f); 


glMatrixMode (GL_MODELVIEW) ; 


glBindTexture(GL_TEXTURE_2D, toTextures[1]); 


// Background texture 
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LISTING 9.1 Continued 
// We will specify texture coordinates 
g1Disable(GL_TEXTURE_GEN_S) ; 
g1Disable(GL_TEXTURE_GEN_T); 


// No depth buffer writes for background 
glDepthMask(GL_FALSE) ; 


// Background image 

glBegin(GL_QUADS) ; 
glTexCoord2f(0.0f, 0.0f); 
glVertex2f(0.0f, 0.0f); 


glTexCoord2f(1.0f, 0.0f); 
glVertex2f(1.0f, 0.0f); 


glTexCoord2f(1.0f, 1.0f); 
glVertex2f(1.0f, 1.0f); 


glTexCoord2f(0.0f, 1.0f); 
glVertex2f(0.0f, 1.0f); 
glEnd(); 


// Back to 3D land 
glMatrixMode (GL_PROJECTION) ; 
glPopMatrix(); 
glMatrixMode(GL_MODELVIEW) ; 


// Turn texgen and depth writing back on 
glEnable(GL_TEXTURE_GEN_S); 
glEnable(GL_TEXTURE_GEN_T); 

glDepthMask (GL_TRUE) ; 


// May need to switch to stripe texture 
if (iRenderMode != 3) 
glBindTexture(GL_TEXTURE_2D, toTextures[]); 


// Save the matrix state and do the rotations 
glPushMatrix(); 

glTranslatef(0.0f, 0.0f, -2.0f); 
glRotatef(xRot, 1.0f, @.0f, 0.0f); 
glRotatef(yRot, 0.0f, 1.0f, 0.0f); 
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// Draw the tours 
gltDrawTorus(@.35, 0.15, 61, 37); 


// Restore the matrix state 
glPopMatrix(); 


// Display the results 
glutSwapBuffers(); 
} 


FETTTLTTTT LTT ATT TAT TATA TAA TT TT TTL 
// This function does any needed initialization on the rendering 

// context. 

void SetupRC() 


{ 

GLbyte *pBytes; // Texture bytes 

GLint iComponents, iWidth, iHeight; // Texture sizes 

GLenum eFormat; // Texture format 
glEnable(GL_DEPTH_TEST) ; // Hidden surface removal 
glFrontFace(GL_CCW) ; // Counterclockwise polygons face out 
glEnable(GL_CULL_FACE) ; // Do not calculate inside of jet 


// White background 
glClearColor(1.0f, 1.0f, 1.0f, 1.0f ); 


// Decal texture environment 
glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_DECAL); 


// Two textures 
glGenTextures(2, toTextures) ; 


FETTTTTTT TTT TTT TAT TA 
// Load the main texture 
glBindTexture(GL_TEXTURE_2D, toTextures[0]); 
pBytes = gltLoadTGA("stripes.tga", &iWidth, &iHeight, 
&iComponents, &eFormat) ; 

glTexImage2D(GL_TEXTURE_2D, ®, iComponents, iWidth, iHeight, 0, 

eFormat, GL_UNSIGNED_BYTE, (void *)pBytes); 
free(pBytes) ; 
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LISTING 9.1 Continued 


glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); 
glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_MAG_ FILTER, GL_LINEAR); 
glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_REPEAT) ; 
glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_REPEAT); 
glEnable(GL_TEXTURE_2D) ; 


LTLTTTTAT TTT TTT TT TTT TTT Tk 

// Load environment map 

glBindTexture(GL_TEXTURE_2D, toTextures[1]); 

pBytes = gltLoadTGA("Environment.tga", &iWidth, &iHeight, 

&iComponents, &eFormat) ; 

glTexImage2D(GL_TEXTURE_2D, ®, iComponents, iWidth, iHeight, 0, 
eFormat, GL_UNSIGNED BYTE, (void *)pBytes); 

free(pBytes) ; 


glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_MIN FILTER, GL_LINEAR); 
glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR); 
glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_REPEAT) ; 
glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_REPEAT) ; 
glEnable(GL_TEXTURE_2D) ; 


// Turn on texture coordinate generation 
glEnable(GL_TEXTURE_GEN_S); 
glEnable(GL_TEXTURE_GEN_T) ; 


// Sphere Map will be the default 

glTexGeni(GL_S, GL_TEXTURE_GEN_MODE, GL_SPHERE_MAP); 
glTexGeni(GL_T, GL_TEXTURE_GEN MODE, GL_SPHERE_MAP); 
} 


FUTTTLTTT TTT TATA TAT AL 
// Handle arrow keys 
void SpecialKeys(int key, int x, int y) 
{ 
if(key == GLUT_KEY_UP) 
xRot-= 5.0f; 


if(key == GLUT_KEY_DOWN) 
xRot += 5.0f; 


if(key == GLUT_KEY_LEFT) 
yRot -= 5.0f; 
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LISTING 9.1 Continued 


if(key == GLUT_KEY_RIGHT) 
yRot += 5.0f; 


if(key > 356.0f) 
xRot = 0.0f; 


if (key < -1.0f) 
xRot = 355.0f; 


if (key > 356.0f) 
yRot = 0.0f; 


if(key < -1.0f) 
yRot = 355.0f; 


// Refresh the Window 
glutPostRedisplay(); 
} 


TUTTTLTTT TATA TTT 
// Reset projection and light position 
void ChangeSize(int w, int h) 

{ 

GLfloat fAspect; 


// Prevent a divide by zero 
if(h == Q) 
h= 1; 


// Set Viewport to window dimensions 
glViewport(®, @, w, h); 


// Reset coordinate system 
glMatrixMode(GL_PROJECTION) ; 
glLoadidentity(); 


fAspect = (GLfloat) w / (GLfloat) h; 
gluPerspective(45.0f, fAspect, 1.0f, 225.0f); 


glMatrixMode(GL_MODELVIEW) ; 
glLoadidentity(); 
} 
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LISTING 9.1 Continued ; 


TULTTLTTTT TTT TTT TATA TTT TT 
// Program Entry Point 
int main(int argc, char* argv[]) 
tc 
glutInit(&argc, argv); 
glutInitDisplayMode(GLUT_DOUBLE | GLUT_RGB | GLUT_DEPTH); 
glutInitWindowSize (800,600) ; 
glutCreateWindow("Texture Coordinate Generation") ; 
glutReshapeFunc(ChangeSize) ; 
glutSpecialFunc(Specialkeys) ; 
glutDisplayFunc(RenderScene) ; 
SetupRC(); 


// Create the Menu 
glutCreateMenu(ProcessMenu) ; 
glutAddMenuEntry( "Object Linear" ,1); 
glutAddMenuEntry("Eye Linear" ,2); 
glutAddMenuEntry("“Sphere Map" ,3) ; 
glutAttachMenu(GLUT_RIGHT_BUTTON) ; 


glutMainLoop(); 


// Don't forget the texture objects 
glDeleteTextures(2, toTextures) ; 


return Q; 


} 


Object Linear Mapping 


When the texture generation mode is set to GL_OBJECT_LINEAR, texture coordinates are 
generated using the following function: 


coord = P1*X + P2*Y + P3*Z + P4*W 


The X, Y, Z, and W values are the vertex coordinates from the object being textured, and 
the P1-P4 values are the coefficients for a plane equation. The texture coordinates are 
then projected onto the geometry from the perspective of this plane. For example, to 
project texture coordinates for S and T from the plane Z = 0, we would use the following 
code from the TEXGEN sample program: 
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// Projection plane 
GLfloat zPlane[] = { 0.0f, 0.0f, 1.0f, 0.0f }; 


// Object Linear 

glTexGeni(GL_S, GL_TEXTURE_GEN_MODE, GL_OBJECT_LINEAR) ; 
glTexGeni(GL_T, GL_TEXTURE_GEN MODE, GL_OBJECT_LINEAR) ; 
glTexGenfv(GL_S, GL_OBJECT_PLANE, zPlane); 
glTexGenfv(GL_T, GL_OBJECT_PLANE, zPlane); 


Note that the texture coordinate generation function can be different for each coordinate. 
Here, we simply use the same function for both the S and T coordinates. 


This technique maps the texture to the object in object coordinates, regardless of any 
ModelView transformation in effect. Figure 9.7 shows the output for TEXGEN when the 
Object Linear mode is selected. No matter how you reorient the torus, the mapping 
remains fixed to the geometry. 


FIGURE 9.7 Torus mapped with object linear coordinates. 
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Eye Linear Mapping 

When the texture generation mode is set to GL_EYE_LINEAR, texture coordinates are gener- 
ated in a similar manner to GL_OBJECT_LINEAR. The coordinate generation looks the same, 
except that now the X, Y, Z, and W coordinates indicate the location of the point of view 
(where the camera or eye is located). The plane equation coefficients are also inverted 
before being applied to the equation. 


The texture, therefore, is basically projected from the plane onto the geometry. As the 
geometry is transformed by the ModelView matrix, the texture will appear to slide across 
the surface. We set up this capability with the following code from the TEXGEN sample 
program: 


// Projection plane 
GLfloat zPlane[] = { 0.0f, 0.0f, 1.0f, O.Of }; 


// Eye Linear 

glTexGeni(GL_S, GL_TEXTURE_GEN_MODE, GL_EYE_LINEAR) ; 
glTexGeni(GL_T, GL_TEXTURE_GEN_MODE, GL_EYE_LINEAR) ; 
glTexGenfv(GL_S, GL_EYE_PLANE, zPlane); 
glTexGenfv(GL_T, GL_EYE_PLANE, zPlane); 


The output of the TEXGEN program when the Eye Linear menu option is selected is 
shown in Figure 9.8. As you move the torus around with the arrow keys, note how the 
projected texture slides about on the geometry. 


Sphere Mapping 

When the texture generation mode is set to GL__SPHERE_MAP, OpenGL calculates texture 
coordinates in such a way that the object appears to be reflecting the current texture map. 
This is the easiest mode to set up, with just these two lines from the TEXGEN sample 
program: 


glTexGeni(GL_S, GL_TEXTURE_GEN MODE, GL_SPHERE MAP); 
glTexGeni(GL_T, GL_TEXTURE_GEN MODE, GL_SPHERE MAP) ; 


You usually can make a well-constructed texture by taking a photograph through a fish- 
eye lens. This texture then lends a convincing reflective quality to the geometry. For more 
realistic results, sphere mapping has largely been replaced by cube mapping (discussed 
next). However, sphere mapping still has some uses. 


In particular, sphere mapping requires only a single texture instead of six, and if true 
reflectivity is not required, you can obtain adequate results from sphere mapping. Even 
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without a well-formed texture taken through a fish-eye lens, you can also use sphere 
mapping for an approximate environment map. Many surfaces are shiny and reflect the 
light from their surroundings, but are not mirror-like in their reflective qualities. In the 
TEXGEN sample program, we use a suitable environment map for the background (all 
modes show this background), as well as the source for the sphere map. Figure 9.9 shows 
the environment-mapped torus against a similarly colored background. Moving the torus 
around with the arrow keys produces a reasonable approximation of a reflective surface. 


FIGURE 9.8 An example of eye linear texture mapping. 


Cube Mapping 

The last two texture generation modes, GL_REFLECTION_MAP and GL_NORMAL_MAP, require 
the use of a new type of texture environment: the cube map. A cube map is not a single 
texture, but rather a set of six textures that make up the six sides of a cube. Figure 9.10 
shows the layout of six square textures comprising a cube map for the CUBEMAP sample 
program. 
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FIGURE 9.9 An environment map using sphere map. 


FIGURE 9.10 Cube map for SphereWorld in the CUBEMAP sample program. 
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These six tiles represent the view of SphereWorld from six different directions (forward, 
backward, left, right, up, and down). Using the texture generation mode 
GL_REFLECTION_MAP, you can then create a truly accurate reflective surface. 


Loading Cube Maps 

Cube maps add six new values that can be passed into glTexImage2D: 
GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, 
GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, 
GL_TEXTURE_CUBE_MAP_POSITIVE_Z, and GL_TEXTURE_CUBE_MAP_NEGATIVE_Z. These 
constants represent the direction in world coordinates of the cube face surrounding the 
object being mapped. For example, to load the map for the positive X direction, you 
might use a function that looks like this: 


glTexImage2D(GL_TEXTURE_CUBE_MAP_POSITIVE_X, @, GL_RGBA, iWidth, iHeight, 
@, GL_RGBA, GL_UNSIGNED_BYTE, pImage) ; 


To take this example further, look at the following code segment from the CUBEMAP 
sample program. Here, we store the name and identifiers of the six cube maps in arrays 
and then use a loop to load all six images into a single texture object: 


const char *szCubeFaces[6] = { “right.tga", “left.tga", “up.tga", "“down.tga", 
“backward.tga", “forward.tga" }; 


GLenum cube[6] = { GL_TEXTURE_CUBE_MAP_POSITIVE_X, 
GL_TEXTURE_CUBE_MAP_NEGATIVE_X, 
GL_TEXTURE_CUBE_MAP_POSITIVE_Y, 
GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, 
GL_TEXTURE_CUBE_MAP_POSITIVE_Z, 
GL_TEXTURE_CUBE_MAP_NEGATIVE_Z }; 


glBindTexture(GL_TEXTURE_CUBE_MAP, textureObjects[CUBE_MAP]) ; 


glTexParameteri(GL_TEXTURE_CUBE_MAP, GL_TEXTURE_MAG FILTER, GL_LINEAR); 
glTexParameteri(GL_TEXTURE_CUBE_MAP, GL_TEXTURE_MIN FILTER, GL_LINEAR); 
glTexParameteri(GL_TEXTURE_CUBE_MAP, GL_TEXTURE_WRAP_S, GL_REPEAT); 
glTexParameteri(GL_TEXTURE_CUBE_MAP, GL_TEXTURE_WRAP_T, GL_REPEAT); 
glTexParameteri(GL_TEXTURE_CUBE_WAP, GL_TEXTURE_WRAP_R, GL_REPEAT); 


// Load Cube Map images 
for(i = 0; i < 6; itt) 
{ 
GLubyte *pBytes; 
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GLint iWidth, iHeight, iComponents; 
GLenum eFormat; 


// Load this texture map 
// glTexParameteri(GL_TEXTURE_CUBE_MAP, GL_GENERATE_MIPMAP, GL_TRUE) ; 
pBytes = gltLoadTGA(szCubeFaces[i], &iWidth, &iHeight, 
&iComponents, &eFormat) ; 

glTexImage2D(cube[i], ®, iComponents, iWidth, iHeight, ®, eFormat, 

GL_UNSIGNED_BYTE, pBytes) ; 
free(pBytes) ; 
} 


Notice how the first parameter to g1BindTexture is now GL_TEXTURE_CUBE_MAP instead of 
GL_TEXTURE_2D. The same value is also used in glEnable to enable cube mapping: 


glEnable(GL_TEXTURE_CUBE_MAP) ; 


If both GL_TEXTURE_CUBE_MAP and GL_TEXTURE_2D are enabled, GL_TEXTURE_CUBE_MAP has 
precedence. Also, notice that the texture parameter values (set with glTexParameter) affect 
all six images in a single cube texture. For all intents and purposes, cube maps are treated 
like a single 3D texture map, using S, T, and R coordinates to interpolate texture coordi- 
nate values. 


Using Cube Maps 

The most common use of cube maps is to create an object that reflects its surroundings. 
The six images used for the CUBEMAP sample program were made from one of the 
SphereWorld samples with the torus and revolving sphere removed. The point of view was 
changed six times and captured (using a 90-degree field of view). These views were then 
assembled into a single cube map using the code from the preceding section, and appear 
something like that shown in Figure 9.9. 


The CUBEMAP sample sets the texture generation mode to GL_REFLECTION_MAP for all 
three texture coordinates: 


glTexGeni(GL_S, GL_TEXTURE_GEN MODE, GL_REFLECTION MAP) ; 
glTexGeni(GL_T, GL_TEXTURE_GEN MODE, GL_REFLECTION_MAP); 
glTexGeni(GL_R, GL_TEXTURE_GEN MODE, GL_REFLECTION MAP); 


Then, when the torus is drawn, 2D texturing is disabled and cube mapping is enabled. 
Texture coordinate generation is enabled and the torus is drawn. Afterward, the normal 
texturing state is restored: 


glDisable(GL_TEXTURE_2D) ; 
glEnable(GL_TEXTURE_CUBE_MAP) ; 
glBindTexture(GL_TEXTURE_CUBE_MAP, textureObjects[CUBE_MAP]) ; 


Multitexture 457 


glEnable(GL_TEXTURE_GEN_S) ; 
glEnable(GL_TEXTURE_GEN_T); 
glEnable(GL_TEXTURE_GEN_R); 
gltDrawTorus(®.35, 0.15, 61, 37); 
glDisable(GL_TEXTURE_GEN S); 
glDisable(GL_TEXTURE_GEN_T); 
glDisable(GL_TEXTURE_GEN_R); 
glDisable(GL_TEXTURE_CUBE_MAP) ; 
glEnable(GL_TEXTURE_2D) ; 


Figure 9.11 shows the output of the CUBEMAP sample program. Notice how the ground is 
reflected correctly off the bottom surfaces of the torus, with the gray sky reflected on the 
upper surfaces. In the same manner, you can see the spheres scattered throughout 
SphereWorld reflected in the sides of the torus. 


ene) Sc] 


FIGURE 9.11 Output from the CUBEMAP sample program. 


Multitexture 


Most modern OpenGL hardware implementations support the ability to apply two or 
more textures to geometry simultaneously. All OpenGL implementations support at least a 
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single texture being applied to geometry. If an implementation supports more than one 
texture unit, you can query with GL_MAX_TEXTURE_UNITS to see how many texture units are 
available: 


GLint iUnits; 
glGetIntegerv(GL_MAX_TEXTURE_UNITS, &iUnits); 


Textures are applied from the base texture unit (GL_TEXTUREQ), up to the maximum 
number of texture units in use (GL_TEXTUREn, where rn is the number of texture units in 
use). Each texture unit has its own texture environment that determines how fragments 
are combined with the previous texture unit. Figure 9.12 shows three textures being 
applied to geometry, each with its own texture environment. 


Texture + 
Environment + 0 


oe . Texture 

ronment + 1 
Environment + UNIT 1 
+ cs 


FIGURE 9.12 Multitexture order of operations. 


By default, the first texture unit is the active texture unit. All texture commands, with 
the exception of glTexCoord, affect the currently active texture unit. You can change the 
current texture unit by calling glActiveTexture with the texture unit identifier as the 
argument. For example, to switch to the second texture unit and enable 2D texturing on 
that unit, you would call the following: 


glActiveTexture(GL_TEXTURE1) ; 
glEnable(GL_TEXTURE_2D) ; 
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To disable texturing on the second texture unit and switch back to the first (base) texture 
unit, you would make these calls: 


glDisable(GL_TEXTURE_2D) ; 
glActiveTexture(GL_TEXTUREQ) ; 


All calls to texture functions such as glTexParameter, glTexEnv, glTexGen, glTexImage, 
and glBindTexture are bound only to the current texture unit. When geometry is 
rendered, texture is applied from all enabled texture units using the texture environment 
and parameters previously specified. The only exception is texture coordinates. 


Multiple Texture Coordinates 


Occasionally, you might apply all active textures using the same texture coordinates for 
each texture, but this is rarely the case. When using multiple textures, you can still specify 
texture coordinates with glTexCoord; however, these texture coordinates are used only for 
the first texture unit (GL_TEXTURE®). To specify texture coordinates separately for each 
texture unit, you need a new texture coordinate function: 


glMultiTexCoord2f(GLenum texUnit, GLfloat s, GLfloat t); 


The texUnit parameter is GL_TEXTUREQ, GL_TEXTURE1, and so on up to the maximum 
number of supported texturing units. In this version of g1MultiTexCoord, you specify the 
s and t coordinates of a two-dimensional texture. Just like g1TexCoord, many variations of 
glMultiTexCoord enable you to specify one-, two-, three-, and four-dimensional texture 
coordinates in a number of different data formats. You can also use texture coordinate 
generation on one or more texture units. 


A Multitextured Example 


Listing 9.2 presents the code for the sample program MULTITEXTURE. This program is 
similar to the CUBEMAP program, and only the changed functions are listed here. In the 
CUBEMAP program, we removed the wood texture from the torus and replaced it with a 
cube map, giving the appearance of a perfectly reflective surface. In MULTITEXTURE, we 
have put the wood texture back on the torus but moved the cube map to the second 
texture unit. We use the GL_MODULATE texture environment to blend the two textures 
together. We have also lightened the textures for the cube map to make the surface 
brighter and the wood easier to see. Figure 9.13 shows the output from the MULTITEX- 
TURE program. 
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TOpenGl SphereWorld Demo + Multitexture Joye! 


FIGURE 9.13 Output from the MULTITEXTURE sample program. 


LISTING 9.2 Source Code for the MULTITEXTURE Sample Program _ 


#include "../../Common/OpenGLSB.h" // System and OpenGL Stuff 
#include “../../Common/GLTools.h" // OpenGL toolkit 
#include <math.h> 


#define NUM_SPHERES 30 
GLTFrame spheres[NUM_SPHERES] ; 
GLTFrame frameCamera; 


// Light and material Data 


GLfloat fLightPos[4] = { -100.0f, 100.0f, 50.0f, 1.0f }; // Point source 
GLfloat fNoLight[] = { @.0f, 0.O0f, 0.0f, O.Of }; 

GLfloat flowLight[] = { 0.25f, 0.25f, 0.25f, 1.0f }; 

GLfloat fBrightLight[] = { 1.0f, 1.0f, 1.0f, 1.0f }; 


#define GROUND_TEXTURE 
#define SPHERE_TEXTURE 
#define WOOD_TEXTURE 
#define CUBE_MAP 
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LISTING 9.2 Continued 


#define NUM_TEXTURES a 
GLuint textureObjects[NUM_TEXTURES] ; 


const char *szTextureFiles[] = {"grass.tga", “orb.tga", "wood.tga"}; 


const char *szCubeFaces[6] = { "right.tga", "left.tga", "“up.tga", 
"down.tga", "“backward.tga", "forward.tga" }; 


GLenum cube[6] = { GL_TEXTURE_CUBE_MAP_POSITIVE_X, 
GL_TEXTURE_CUBE_MAP_NEGATIVE_X, 
GL_TEXTURE_CUBE_MAP_POSITIVE_Y, 
GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, 
GL_TEXTURE_CUBE_MAP_POSITIVE_Z, 
GL_TEXTURE_CUBE_MAP_NEGATIVE_Z }; 


LTTTLTTTT TTT TTT TTT TTT 
// This function does any needed initialization on the rendering 
// context. 
void SetupRC() 

{ 

int iSphere; 

int i; 


// Grayish background 
glClearColor(fLowLight[®], flowLight[1], flowLight[2], flowLight[3]); 


// Cull backs of polygons 
glCullFace(GL_BACK) ; 
glFrontFace(GL_CCW) ; 
glEnable(GL_CULL_FACE) ; 
glEnable(GL_DEPTH_TEST) ; 


// Setup light Parameters: 

glLightModelfv(GL_LIGHT_MODEL_AMBIENT, fNoLight) ; 
glLightModeli(GL_LIGHT_MODEL_COLOR_CONTROL, GL_SEPARATE_SPECULAR_COLOR) ; 
glLightfv(GL_LIGHTO, GL_AMBIENT, fLowLight) ; 

glLightfv(GL_LIGHT®, GL_DIFFUSE, fBrightLight) ; 

glLightfv(GL_LIGHT@, GL_SPECULAR, fBrightLight) ; 

glEnable(GL_LIGHTING) ; 

glEnable(GL_LIGHT®) ; 
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LISTING 9.2 Continued 


// Mostly use material tracking 
glEnable(GL_COLOR_MATERIAL) ; 
glColorMaterial(GL_FRONT, GL_AMBIENT_AND DIFFUSE) ; 
glMateriali(GL_FRONT, GL_SHININESS, 128); 


gltInitFrame(&frameCamera); // Initialize the camera 


// Randomly place the sphere inhabitants 
for(iSphere = @; iSphere < NUM_SPHERES; iSphere++) 
{ 


gltInitFrame(&spheres[iSphere]) ; // Initialize the frame 


// Pick a random location between -20 and 20 at .1 increments 
spheres[iSphere].vLocation[®] = (float)((rand() % 400) - 200) * 0.1f; 
spheres[iSphere].vLocation[1] = 0.0f; 

spheres[iSphere].vLocation[2] = (float)((rand() % 400) - 200) * 0.1f; 
} 


// Set up texture maps 
glEnable(GL_TEXTURE_2D) ; 

glGenTextures(NUM_TEXTURES, textureObjects) ; 
glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE) ; 


// Load regular textures 
for(i = @; i < CUBE_MAP; i++) 
{ 
GLubyte *pBytes; 
GLint iWidth, iHeight, iComponents; 
GLenum eFormat; 


glBindTexture(GL_TEXTURE_2D, textureObjects[i]); 


// Load this texture map 
glTexParameteri(GL_TEXTURE_2D, GL_GENERATE_MIPMAP, GL_TRUE) ; 
pBytes = gltLoadTGA(szTextureFiles[i], &iWidth, &iHeight, 
&iComponents, &eFormat) ; 
glTexImage2D(GL_TEXTURE_2D, @, GL_COMPRESSED_RGB, iWidth, iHeight, 
®, eFormat, GL_UNSIGNED BYTE, pBytes); 
free(pBytes) ; 


glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG FILTER, GL_LINEAR) ; 
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LISTING 9.2 Continued 


glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN FILTER, 

GL_LINEAR_MIPMAP_LINEAR) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE); 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE); 
} 


glActiveTexture(GL_TEXTURE1) ; 

glDisable(GL_TEXTURE_2D) ; 

glEnable(GL_TEXTURE_CUBE_MAP) ; 
glBindTexture(GL_TEXTURE_CUBE_MAP, textureObjects[CUBE_MAP]) ; 
glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE) ; 


glTexGeni(GL_S, GL_TEXTURE_GEN MODE, GL_REFLECTION MAP) ; 
glTexGeni(GL_T, GL_TEXTURE_GEN MODE, GL_REFLECTION_MAP) ; 
glTexGeni(GL_R, GL_TEXTURE_GEN MODE, GL_REFLECTION MAP) ; 
glEnable(GL_TEXTURE_GEN_S); 
glEnable(GL_TEXTURE_GEN_T); 
glEnable(GL_TEXTURE_GEN_R); 


glBindTexture(GL_TEXTURE_CUBE_MAP, textureObjects[CUBE_MAP]); 


glTexParameteri(GL_TEXTURE_CUBE_MAP, GL_TEXTURE_MAG FILTER, GL_LINEAR) ; 
glTexParameteri(GL_TEXTURE_CUBE_MAP, GL_TEXTURE_MIN FILTER, GL_LINEAR); 
glTexParameteri(GL_TEXTURE_CUBE_MAP, GL_TEXTURE_WRAP_S, GL_REPEAT); 
glTexParameteri(GL_TEXTURE_CUBE_MAP, GL_TEXTURE_WRAP_T, GL_REPEAT) ; 
glTexParameteri(GL_TEXTURE_CUBE_MAP, GL_TEXTURE_WRAP_R, GL_REPEAT); 


// Load Cube Map images 
for(i = 0; i < 6; i++) 
{ 
GLubyte *pBytes; 
GLint iWidth, iHeight, iComponents; 
GLenum eFormat; 


// Load this texture map 
// glTexParameteri(GL_TEXTURE_CUBE_MAP, GL_GENERATE_MIPMAP, GL_TRUE) ; 
pBytes = gltLoadTGA(szCubeFaces[i], &iWidth, &iHeight, 
&iComponents, &eFormat) ; 
glTexImage2D(cube[i], ®, iComponents, iWidth, iHeight, 0, 
eFormat, GL_UNSIGNED BYTE, pBytes) ; 
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LISTING 9.2. Continued 


free(pBytes) ; 
} 


FTTTTTTTTLTLT TTT TT TTA TTT TATA TAA AA ALAA 
// Draw random inhabitants and the rotating torus/sphere duo 
void DrawInhabitants (void) 
{ 
static GLfloat yRot = 0.0f; // Rotation angle for animation 
GLint i; 


yRot += 0.5f; 
glColor4f(1.0f, 1.0f, 1.0f, 1.0f); 


// Draw the randomly located spheres 
glBindTexture(GL_TEXTURE_2D, textureObjects[SPHERE_TEXTURE]); 
for(i = 0; i < NUM_SPHERES; i++) 

{ 

glPushMatrix(); 

gltApplyActorTransform(&spheres[i]); 

gltDrawSphere(@.3f, 21, 11); 

glPopMatrix(); 

} 


glPushMatrix(); 
glTranslatef(0.0f, @.1f, -2.5f); 


// Torus alone will be specular 
glMaterialfv(GL_FRONT, GL_SPECULAR, fBrightLight) ; 
glRotatef(yRot, 0.0f, 1.0f, 0.0f); 


// Bind to Wood, first texture 
glBindTexture(GL_TEXTURE_2D, textureObjects[WOOD TEXTURE] ); 


glActiveTexture(GL_TEXTURE1) ; 
glEnable(GL_TEXTURE_CUBE_MAP) ; 


glActiveTexture(GL_TEXTUREQ) ; 
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LISTING 9.2 Continued 
gltDrawTorus(@.35, @.15, 41, 17); 


glActiveTexture(GL_TEXTURE1) ; 
glDisable(GL_TEXTURE_CUBE_MAP) ; 
glActiveTexture(GL_TEXTURE®) ; 


glMaterialfv(GL_FRONT, GL_SPECULAR, fNoLight) ; 
glPopMatrix(); 
} 


Texture Combiners 


In Chapter 6, “More on Colors and Materials,” you learned how to use the blending equa- 
tion to control the way color fragments were blended together when multiple layers of 
geometry were drawn in the color buffer (typically back to front). OpenGL’s texture 
combiners allow the same sort of control (only better) for the way multiple texture frag- 
ments are combined. By default, you can simply choose one of the texture environment 
modes (GL_DECAL, GL_REPLACE, GL_MODULATE, or GL_ADD) for each texture unit, and the 
results of each texture application are then added to the next texture unit. These texture 
environments were covered in Chapter 8. 


Texture combiners add a new texture environment, GL_COMBINE, that allows you to explic- 
itly set the way texture fragments from each texture unit are combined. To use texture 
combiners, you call glTexEnv in the following manner: 


glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_COMBINE) ; 


Texture combiners are controlled entirely through the glTexEnv function. Next, you need 
to select which texture combiner function you want to use. The combiner function selec- 
tor, which can be either GL_COMBINE_RGB or GL_COMBINE_ALPHA, becomes the second argu- 
ment to the glTexEnv function. The third argument becomes the texture environment 
function that you want to employ (for either RGB or alpha values). These functions are 
listed in Table 9.4. For example, to select the GL_REPLACE combiner for RGB values, you 
would call the following function: 


glTexEnvi(GL_TEXTURE_ENV, GL_COMBINE_RGB, GL_REPLACE) ; 


This combiner does little more than duplicate the normal GL_REPLACE texture environ- 
ment. 
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TABLE 9.4 Texture Combiner Functions 


Constant Function 

GL_REPLACE ArgO 

GL_MODULATE ArgO * Arg] 

GL_ADD ArgO + Arg1 

GL_ADD_SIGNED ArgO + Arg] - 0.5 

GL_INTERPOLATE (ArgO * Arg2) + (Arg1 * (1 - Arg2)) 

GL_SUBTRACT ArgO - Arg] 

GL_DOT3_RGB/GL_DOT3_RGBA 4*((ArgOr — 0.5) * (Argir — 0.5) + (Arg0g — 0.5) * (Arglg - 0.5) 


+ (ArgOb - 0.5) * (Arg1b - 0.5)) 


The values of ArgO — Arg2 are from source and operand values set with more calls to 
glTexEnv. The values GL_SOURCEx_RGB and GL_SOURCEx_ALPHA are used to specify the RGB 
or alpha combiner function arguments, where x is 0, 1, or 2. The values for these sources 
are given in Table 9.5. 


TABLE 9.5 Texture Combiner Sources 


Constant Description 

GL_TEXTURE The texture bound to the current active texture unit 
GL_TEXTUREx The texture bound to texture unit x 

GL_CONSTANT The color (or alpha) value set by the texture environment variable 


GL_TEXTURE_ENV_COLOR 
GL_PRIMARY_COLOR _ The color (or alpha) value coming from the original geometry fragment 
GL_PREVIOUS The color (or alpha) value resulting from the previous texture unit’s texture envi- 
ronment 


For example, to select the texture from texture unit 0 for Arg0, you would make the 
following function call: 


glTexEnvi(GL_TEXTURE_ENV, GL_SOURCE® RGB, GL_TEXTUREQ); 


You also have some additional control over what values are used from a given source for 
each argument. To set these operands, you use the constant GL_OPERANDx_RGB or 
GL_OPERANDx_ALPHA, where x is 0, 1, or 2. The valid operands and their meanings are given 
in Table 9.6. 


TABLE 9.6 Texture Combiner Operands 
Constant Meaning 


GL_SRC_COLOR The color values from the source. This may not be used with 
GL_OPERANDx_ALPHA. 

GL_ONE_MINUS_SRC_COLOR One’s complement (1-value) of the color values from the source. This 
may not be used with GL_OPERANDx_ALPHA. 

GL_SRC_ALPHA The alpha values of the source. 

GL_ONE_MINUS_SRC_ALPHA One’s complement (1-value) of the alpha values from the source. 
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For example, if you have two textures loaded on the first two texture units, and you want 
to multiply the color values from both textures during the texture application, you would 
set it up as follows: 


// Tell OpenGL you want to use texture combiners 
glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_COMBINE) ; 


// Tell OpenGL which combiner you want to use (GL_MODULATE for RGB values) 
glTexEnvi(GL_TEXTURE_ENV, GL_COMBINE_RGB, GL_MODULATE) ; 


// Tell OpenGL to use texture unit @'s color values for Arg® 
glTexEnvi(GL_TEXTURE_ENV, GL_SOURCE@_RGB, GL_TEXTURE®O) ; 
glTexEnvi(GL_TEXTURE_ENV, GL_OPERAND@ RGB, GL_SRC_COLOR) ; 


// Tell OpenGL to use texture unit 1's color values for Arg1 
glTexEnvi(GL_TEXTURE_ENV, GL_SOURCE@_RGB, GL_TEXTURE1); 
glTexenvi(GL_TEXTURE_ENV, GL_OPERAND@ RGB, GL_SRC_COLOR); 


Finally, with texture combiners, you can also specify a constant RGB or alpha scaling 
factor. The default parameters for these are as follows: 


glTexEnvf(GL_TEXTURE_ENV, GL_RGB_SCALE, 1.0f); 
glTexEnvf(GL_TEXTURE_ENV, GL_ALPHA SCALE, 1.0f); 


Summary 


In this chapter, we took texture mapping beyond the simple basics of applying a texture to 
geometry. You saw how to get improved filtering, obtain better performance and memory 
efficiency through texture compression, and generate automatic texture coordinates for 
geometry. You also saw how to add plausible environment maps with sphere mapping and 
more realistic and correct reflections using cube maps. 


Finally, we discussed multitexture and texture combiners. The ability to apply more than 
one texture at a time is the foundation for many special effects, including hardware 
support for bump mapping. Using texture combiners, you have a great deal of flexibility 
in specifying how up to three textures are combined. While fragment programs exposed 
through the new OpenGL shading language do give you ultimate control over texture 
application, you can quickly and easily take advantage of the capabilities described in this 
chapter. 


Reference 


glActiveTexture 


Purpose: Sets the active texture unit. 
Include File: <gl.h> 
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Syntax: 


void glActiveTexture(GLenum texUnit) ; 


Description: 
Parameters: 
texUnit 


Returns: 
See Also: 


This function sets the active texture unit. The active texture unit is the 
target of all texture functions with the exception of gl1TexCoord and 
glTexCoordPointer. 


GLenum: The texture unit to be made current. It may be GL_TEXTUREO 
through GL_TEXTUREn, where n is the number of supported texture units. 


None. 
glClientActiveTexture 


glClientActiveTexture 


Purpose: 
Include File: 
Syntax: 


Sets the active texture unit for vertex arrays. 
<gl.h> 


void glClientActiveTexture(GLenum texUnit) ; 


Description: 


This function sets the active texture unit for vertex array texture coordi- 
nate specification. The g1TexCoordPointer vertex array function (see 
Chapter 11), by default, specifies a pointer for the first texture unit 
(GL_TEXTURE®@). You use this function to change the texture unit that is 
the target of glTexCoordPointer. Calling this function multiple times 
allows you to specify multiple arrays of texture coordinates for multitex- 
tured vertex array operations. 


Parameters: 

texUnit GLenumm: The texture unit to be made current. It may be GL_TEXTUREQ 
through GL_TEXTUREn, where n is the number of supported texture units. 

Returns: None. 

See Also: glActiveTexture 

glCompressedTexImage 

Purpose: Loads a compressed texture image. 


Include File: 
Variations: 


<gl.h> 


void glCompressedTexImage1D(GLenum target, GLint level, GLenum internalFormat, 


GLsizei width, 
GLint border, GLsizei imageSize, void *data); 
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void glCompressedTexImage2D(GLenum target, GLint level, GLenum internalFormat, 
GLsizei width, GLsizei height, 
GLint border, GLsizei imageSize, void *data); 

void glCompressedTexImage3D(GLenum target, GLint level, GLenum internalFormat, 
GLsizei width, Glsizei height, Glsizei depth, 
GLint border, Glsizei imageSize, GLvoid *data); 


Description: This function enables you to load a compressed texture image. This func- 
tion is nearly identical in use to the glTexImage family of functions, with 
the exception that the internalFormat parameter must specify a 
supported compressed texture format. 

Parameters: 


target GLenum: It must be GL_TEXTURE_1D for g1CompressedTexImage1D, 
GL_TEXTURE_2D for glCompressedTexImage2D, or GL_TEXTURE_3D for 
glCompressedTexImage3D. For 2D cube maps only, it may also be 
GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, 
GL_CUBE_MAP_POSITIVE_Y, GL_CUBE_MAP_NEGATIVE_Y, GL_CUBE_MAP_ 
POSITIVE_Z, or GL_CUBE_MAP_NEGATIVE_Z. 

level GLint: The level of detail. It is usually 0 unless mipmapping is used. 

internalFormat GLint: The internal format of the compressed data. Specific values for 
texture compression formats will vary from implementation to imple- 
mentation. Table 9.3 lists the formats for one commonly supported 
compression format on the PC and Macintosh. 


width GLsizei: The width of the one-, two-, or three-dimensional texture 
image. It must be a power of 2 but may include a border. 

height GLsizei: The height of the two- or three-dimensional texture image. It 
must be a power of 2 but may include a border. 

depth GLsizei: The depth of a three-dimensional texture image. It must be a 
power of 2 but may include a border. 

border GLint: The width of the border. Not all texture compression formats 
support borders. 

imageSize GLsizei: The size in bytes of the compressed data. 

data GLvoid *: The compressed texture data. 

Returns: None. 

See Also: glCompressedTexSubImage, glTexImage 


glCompressedTexSubImage 


Purpose: Replaces a portion of an existing compressed texture map. 
Include File: <gl.h> 
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Variations: 


void glCompressedTexSubImage1D(GLenum target, GLint level, 


GLint xOffset, 
GLsizei width, 
GLsizei imageSize, const void *data); 


void glCompressedTexSubImage2D(GLenum target, GLint level, 


GLint xOffset, GLint yOffset, 
GLsizei width, GLsizei height, 
GLsizei imageSize, const void *data); 


void glCompressedTexSubImage3D(GLenum target, GLint level, 


Description: 


Parameters: 


target 
level 
xOffset 


yOffset 
z0ffset 
width 
height 
depth 
imageSize 


data 


Returns: 
See Also: 


GLint xOffset, GLint yOffset, GLint zOffset, 
GLsizei width, GLsizei height, GLsizei depth, 
GLsizei imageSize, const void *data); 


This function replaces a portion of an existing one-, two-, or three- 
dimensional compressed texture map. Updating all or part of an existing 
texture map may be considerably faster than reloading a texture image 
with glCompressedTexImage. You cannot perform an initial texture load 
with this function; it is used only to update an existing texture. 


GLenum: It must be GL_TEXTURE_1D, GL_TEXTURE_2D, or GL_TEXTURE_3D. 
GLint: Mipmap level to be updated. 


GLint: Offset within the existing one-, two-, or three-dimensional texture 
in the x direction to begin the update. 


GLint: Offset within the existing two- or three-dimensional texture in the 
y direction to begin the update. 


GLint: Offset within the existing three-dimensional texture in the z direc- 
tion to begin the update. 


GLsizei: The width of the one-, two-, or three-dimensional texture data 
being updated. 


GLsizei: The height of the two- or three-dimensional texture data being 
updated. 


GLsizei: The depth of the three-dimensional texture data being updated. 
GLsizei: The size in bytes of the compressed texture data. 


const void*: A pointer to the compressed texture data that is being used 
to update the texture target. 


None. 
glCompressedTexImage, glTexSubImage 
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glGetCompressedTexImage 


Purpose: Returns a compressed texture image. 
Include File: <gl.h> 
Syntax: 


void glGetCompressedTexImage(GLenum target, GLint level, void *pixels); 


Description: This function enables you to fill a data buffer with the data that 
comprises the current compressed texture. This function performs the 
reverse operation of glCompressedTexImage, which loads a compressed 
texture with a supplied data buffer. You cannot use this function to 
retrieve a compressed version of an uncompressed texture. 


Parameters: 

target GLenum: The texture target to be copied. It must be GL_TEXTURE_1D, 
GL_TEXTURE_2D, GL_TEXTURE_3D, GL_TEXTURE_CUBE_MAP_POSITIVE_X, 
GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y, 
GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, or 
GL_TEXTURE_CUBE_MAP_NEGATIVE_Z. 

level GLint: The mipmap level to be read. 

pixels void*: A pointer to a memory buffer to accept the compressed texture 
image. 

Returns: None. 

See Also: glCompressedTexImage, glCompressedTexSubImage, glGetTexImage 

glMultiTexCoord 

Purpose: Specifies the current texture image coordinate for the specified texture 
unit. 


Include File: <gl.h> 
Variations: 


void glMultiTexCoordid(GLenum texUnit, GLdouble s); 

void glMultiTexCoordidv(GLenum texUnit, GLdouble *v); 
void glMultiTexCoord1i(GLenum texUnit, GLint s); 

void glMultiTexCoord1iv(GLenum texUnit, GLint *v); 

void glMultiTexCoordis(GLenum texUnit, GLshort s); 

void glMultiTexCoordisv(GLenum texUnit, GLshort *v); 

void glMultiTexCoord1if(GLenum texUnit, GLfloat s); 

void glMultiTexCoordifv(GLenum texUnit, GLfloat *v); 

void glMultiTexCoord2i(GLenum texUnit, GLint s, GLint t); 
void glMultiTexCoord2iv(GLenum texUnit, GLint *v); 
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void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 


glMultiTexCoord2s(GLenum texUnit, GLshort s, GLshort t); 
glMultiTexCoord2sv(GLenum texUnit, GLshort *v); 
glMultiTexCoord2f(GLenum texUnit, GLfloat s, GLfloat t); 
glMultiTexCoord2fv(GLenum texUnit, GLfloat *v); 
glMultiTexCoord2d(GLenum texUnit, GLdouble s, GLdouble t); 
glMultiTexCoord2dv(GLenum texUnit, GLdouble *v); 
glMultiTexCoord3s(GLenum texUnit, GLshort s, GLshort t, GLshort r); 
glMultiTexCoord3sv(GLenum texUnit, GLshort *v); 
glMultiTexCoord3i(GLenum texUnit, GLint s, GLint t, GLint r); 
glMultiTexCoord3iv(GLenum texUnit, GLint *v); 
glMultiTexCoord3f(GLenum texUnit, GLfloat s, GLfloat t, GLfloat r); 
glMultiTexCoord3fv(GLenum texUnit, GLfloat *v); 
glMultiTexCoord3d(GLenum texUnit, GLdouble s, GLdouble t, GLdouble r); 
glMultiTexCoord3dv(GLenum texUnit, GLdouble *v); 
glMultiTexCoord4f(GLenum texUnit, GLfloat s, GLfloat t, GLfloat r, 


GLfloat q); 


void 
void 


glMultiTexCoord4fv(GLenum texUnit, GLfloat *v); 
glMultiTexCoord4d(GLenum texUnit, GLdouble s, GlLdouble t, GLdouble r, 


GLdouble q); 


void 
void 
void 
void 


glMultiTexCoord4dv(GLenum texUnit, GLdouble *v); 
glMultiTexCoord4i(GLenum texUnit, GLint s, GLint t, GLint r, Glint q); 
glMultiTexCoord4iv(GLenum texUnit, GLint *v); 

glMultiTexCoord4s(GLenum texUnit, GLshort s, GLshort t, GLshort r, 


GLshort q); 


void 


glMultiTexCoord4sv(GLenum texUnit, GLshort *v); 


Description: These functions set the current texture image coordinate for a specific 


texture unit in one to four dimensions. Texture coordinates can be 
updated anytime between glBegin and glEnd, and correspond to the 
following glVertex call. The texture g coordinate is used to scale the s, t, 
and r coordinate values and, by default, is 1.0. Any valid matrix opera- 
tion can be performed on texture coordinates by specifying GL_TEXTURE 
as the target of glMatrixMode. 


Parameters: 

texUnit GLenum: The texture unit this texture coordinate applies to. It may be any 
value from GL_TEXTURE®@ to GL_TEXTUREn, where n is the number of 
supported texture units. 

s GLdouble or GLfloat or GLint or GLshort: The horizontal texture image 
coordinate. 

t GLdouble or GLfloat or GLint or GLshort: The vertical texture image 


coordinate. 


Reference 


r GLdouble or GLfloat or GLint or GLshort: The texture image depth coor- 
dinate. 

q GLdouble or GLfloat or GLint or GLshort: The texture image scaling value 
coordinate. 

Vv GLdouble* or GLfloat* or GLint* or GLshort* 

Returns: None. 

See Also: glTexGen, glTexImage, glTexParameter, glTexCoord 

glSecondaryColor 

Purpose: Specifies a secondary color. 

Include File: <gl.h> 

Variations: 

void glSecondaryColor3b(GLbyte red, GLbyte green, GLbyte blue); 

void glSecondaryColor3s(GLshort red, GLshort green, GLshort blue); 

void glSecondaryColor3i(GLint red, GLint green, GLint blue); 

void glSecondaryColor3f(GLclampf red, GLclampf green, GLclampf blue); 

void glSecondaryColor3d(GLclampd red, GLclampd green, GLclampd blue); 

void glSecondaryColor3ub(GLubyte red, GLubyte green, GLubyte blue); 

void glSecondaryColor3us(GLushort red, GLushort green, GLushort blue) ; 

void glSeconaryColor3ui(GLuint red, GLuint green, GLuint blue); 

void glSeconaryColor3bv(GLbyte* values) ; 

void glSecondaryColor3sv(GLshort* values) ; 

void glSecondaryColor3iv(GLint* values) ; 

void glSecondaryColor3fv(GLclampf* values) ; 

void glSecondaryColor3dv(GLclampd* values) ; 

void glSecondaryColor3ubv(GLubyte* values) ; 

void glSecondaryColor3usv(GLushort* values) ; 

void glSecondaryColor3uiv(GLuint* values) ; 


Description: When objects are texture mapped, specular highlights are typically muted 


by the application of texture after lighting. You can compensate for this 
effect by setting the GL_LIGHT_MODEL_COLOR_CONTROL light model parame- 
ter, which uses the specular lighting and material values for a secondary 
color added after the texture. This function allows you to specify a sepa- 
rate secondary color value that is added to fragments when lighting is 
not enabled—for example, if you were doing your own lighting calcula- 
tions. Calls to glSecondaryColor have no effect when lighting is enabled. 
The color sum operation must be enabled with glEnable(GL_COLOR_SUM). 
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Parameters: 
red 

green 

blue 
values 
Returns: 
See Also: 


glTexGen 
Purpose: 
Include File: 
Syntax: 


Specifies the red component of the color. 
Specifies the green component of the color. 
Specifies the blue component of the color. 
Specifies a pointer to the color component values. 
None. 

glColor 


Defines parameters for texture coordinate generation. 
<gl.h> 


void glTexGend(GLenum coord, GLenum pname, GLdouble param); 
void glTexGenf(GLenum coord, GLenum pname, GLfloat param); 
void glTexGeni(GLenum coord, GLenum pname, GLint param); 

void glTexGendv(GLenum coord, GLenum pname, GLdouble *param) ; 
void glTexGenfv(GLenum coord, GLenum pname, GLfloat *param) ; 
void glTexGeniv(GLenum coord, GLenum pname, GLint *param) ; 


Description: 


Parameters: 


coord 


pname 


This function sets parameters for texture coordinate generation when one 
or more of GL_TEXTURE_GEN_S, GL_TEXTURE_GEN_T, GL_TEXTURE_GEN_R, or 
GL_TEXTURE_GEN_Q is enabled with glEnable. When GL_TEXTURE_GEN_MODE 
is set to GL_OBJECT_LINEAR, texture coordinates are generated by multi- 
plying the current object (vertex) coordinates by the constant vector 
specified by GL_OBJECT_PLANE: 


coordinate = v[®] * p[0] + v[1] * p[1] + v[2] * p[2] + v[3] * p[3] 


For GL_EYE_LINEAR, the eye coordinates (object coordinates multiplied 
through the GL_MODELVIEW matrix) are used. When GL_TEXTURE_GEN_MODE 
is set to GL_SPHERE_MAP, coordinates are generated in a sphere about the 
current viewing position or origin. When GL_TEXTURE_REFLECTION_MAP is 
specified, texture coordinates are calculated as a reflection from the 
current cube map. Finally, GL_TEXTURE_NORMAL_MAP also works with cube 
maps but transforms the object’s normal to eye coordinates (instead of 
vertex) and uses them for texture coordinates. 


GLenum: The texture coordinate to map. It must be one of GL_S, GL_T, 
GL_R, or GL_Q. 


GLenum: The parameter to set. It must be one of GL_TEXTURE_GEN_MODE, 
GL_OBJECT_PLANE, or GL_EYE_PLANE. 


param 


Returns: 
See Also: 
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The parameter value. For GL__TEXTURE_GEN_MODE, param is one of the 
following: 

GL_OBJECT_LINEAR: Texture coordinates are calculated from object (vertex) 
coordinates. 


GL_EYE_LINEAR: Texture coordinates are calculated by eye coordinates 
(object coordinates multiplied through the GL_MODELVIEW matrix). 


GL_SPHERE_MAP: Texture coordinates are generated in a sphere around the 
viewing position. 

GL_REFLECTION_MAP: Texture coordinates are generated using a cube map 
and are reflected from vertices. 


GL_NORMAL_MAP: Texture coordinates are generated using a cube map and 
are based on an objects normals transformed into eye coordinates. 


For GL_OBJECT_PLANE and GL_EYE_PLANE, param is a four-element array 
used as a multiplier for object or eye coordinates. 


None. 
glTexCoord, glTexEnv, glTexImage1D, glTexImage2D, glTexParameter 
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CHAPTER 10 


Curves and Surfaces 


by Richard S. Wright, Jr. 


WHAT YOU’LL LEARN IN THIS CHAPTER: 


How To Functions You'll Use 
Draw spheres, cylinders, and disks gluSphere/gluCylinder/gluDisk 
Use maps to render Bézier glMap/glEvalCoord 


curves and surfaces 

Use evaluators to simplify surface mapping g1lMapGrid/glEvalMesh 

Create NURBS surfaces gluNewNurbsRenderer/gluBeginSurface/ 
gluNurbsSurface/ gluEndSurface/ 
gluDeleteNurbsRendererf10 

Create trimming curves gluBeginTrim/gluPwlCurve/gluEndTrim 

Tessellate concave and convex polygons gluTessBeginPolygon/gluTessEndPolygon 


The practice of 3D graphics is little more than a computerized version of connect-the-dots. 
Vertices are laid out in 3D space and connected by flat primitives. Smooth curves and 
surfaces are approximated using flat polygons and shading tricks. The more polygons 
used, usually the more smooth and curved a surface may appear. OpenGL, of course, 
supports smooth curves and surfaces implicitly because you can specify as many vertices 
as you want and set any desired or calculated values for normals and color values. 


OpenGL does provide some additional support, however, that makes the task of construct- 
ing more complex surfaces a bit easier. The easiest to use are some GLU functions that 
render spheres, cylinders, cones (special types of cylinders, as you will see), and flat, round 
disks, optionally with holes in them. OpenGL also provides top-notch support for 
complex surfaces that may be difficult to model with a simple mathematical equation: 
Bézier and NURB curves and surfaces. Finally, OpenGL can take large, irregular, and 
concave polygons and break them up into smaller, more manageable pieces. 
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Built-in Surfaces 


The OpenGL Utility Library (GLU) that accompanies OpenGL contains a number of func- 
tions that render three quadratic surfaces. These quadric functions render spheres, cylin- 
ders, and disks. You can specify the radius of both ends of a cylinder. Setting one end’s 
radius to 0 produces a cone. Disks, likewise, provide enough flexibility for you to specify a 
hole in the center (producing a washer-like surface). You can see these basic shapes illus- 
trated graphically in Figure 10.1. 


eliieo 


Sphere Cylinder Flat disc Disc with 
hole 


FIGURE 10.1 Possible quadric shapes. 


These quadric objects can be arranged to create more complex models. For example, you 
could create a 3D molecular modeling program using just spheres and cylinders. Figure 
10.2 shows the 3D unit axes drawn with a sphere, three cylinders, three cones, and three 
disks. This model can be included into any of your own programs using the following 
glTools function: 


void gltDrawUnitAxes (void) 


Setting Quadric States 


The quadric surfaces can be drawn with some flexibility as to whether normals, texture 
coordinates, and so on are specified. Putting all these options into parameters to a sphere 
drawing function, for example, would create a function with an exceedingly long list of 
parameters that must be specified each time. Instead, the quadric functions use an object- 
oriented model. Essentially, you create a quadric object and set its rendering state with one 
or more state setting functions. Then you specify this object when drawing one of the 
surfaces, and its state determines how the surface is rendered. The following code segment 
shows how to create an empty quadric object and later delete it: 


GLUquadricObj *p0bj; 

1k Rae tae 

pObj = gluNewQuadric(); // Create and initialize Quadric 
// Set Quadric rendering Parameters 

// Draw Quadric surfaces 

1 orale 

gluDeleteQuadric(pObj); // Free Quadric object 
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FIGURE 10.2 The x,y,z-axes drawn with quadrics. 


Note that you create a pointer to the GLUQuadricObj data type, not an instance of the data 
structure itself. The reason is that the gluNewQuadric function not only allocates space for 
it, but also initializes the structure members to reasonable default values. 


There are four functions that you can use to modify the drawing state of the 
GLUQuadricObj object and, correspondingly, to any surfaces drawn with it. The first func- 
tion sets the quadric draw style: 


void gluQuadricDrawStyle(GLUquadricObj *obj, GLenum drawStyle) ; 


The first parameter is the pointer to the quadric object to be set, and the drawStyle para- 
meter is one of the values in Table 10.1. 


TABLE 10.1 Quadric Draw Styles 


Constant Description: 

GLU_FILL Quadric objects are drawn as solid objects. 
GLU_LINE Quadric objects are drawn as wireframe objects. 
GLU_POINT Quadric objects are drawn as a set of vertex points. 


GLU_SILHOUETTE This is similar to a wireframe, except adjoining faces of polygons are not drawn. 
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The next function specifies whether the quadric surface geometry would be generated 
with surface normals: 


void gluQuadricNormals(GLUquadricObj *pbj, GLenum normals); 


Quadrics may be drawn without normals (GLU_NONE), with smooth normals (GLU_SMOOTH), 
or flat normals (GLU_FLAT). The primary difference between smooth and flat normals is 
that for smooth normals, one normal is specified for each vertex of the surface, giving a 
smoothed-out appearance. For flat normals, one normal is used for all the vertices of any 
given facet (triangle) of the surface. 


You can also specify whether the normals point out of the surface or inward. For example, 
looking at a lit sphere, you would want normals pointing outward from the surface of the 
sphere. However, if you were drawing the inside of a sphere--say, as part of a vaulted 
ceiling--you would want the normals and lighting to be applied to the inside of the 
sphere. The following function sets this parameter: 


void gluQuadricOrientation(GLUquadricObj *obj, GLenum orientation) ; 


Here, orientation can be either GLU_OUTSIDE or GLU_INSIDE. By default, quadric surfaces 
are wound counterclockwise, with the front faces facing the outsides of the surfaces. The 
outside of the surface is intuitive for spheres and cylinders; for disks, it is simply the side 
facing the positive z-axis. 


Finally, you can request that texture coordinates be generated for quadric surfaces with the 
following function: 


void gluQuadricTexture(GLUquadricObj *obj, GLenum textureCoords) ; 


Here, the textureCoords parameter can be either GL_TRUE or GL_FALSE. When texture coor- 
dinates are generated for quadric surfaces, they are wrapped around spheres and cylinders 
evenly; they are applied to disks using the center of the texture for the center of the disk, 
and the edges of the texture lining up with the edges of the disk. 


Drawing Quadrics 


After the quadric object state has been set satisfactorily, each surface is drawn with a single 
function call. For example, to draw a sphere, you simply call the following function: 


void gluSphere(GLUQuadricObj *obj, GLdouble radius, GLint slices, GLint stacks); 


The first parameter, obj, is just the pointer to the quadric object that was previously set up 
for the desired rendering state. The radius parameter is then the radius of the sphere, 
followed by the number of slices and stacks. Spheres are drawn with rings of triangle 
strips (or quad strips, depending on whose GLU library you’re using) stacked from the 
bottom to the top, as shown in Figure 10.3. The number of slices specifies how many 
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triangle sets (or quads) are used to go all the way around the sphere. You could also think 
of this as the number of lines of latitude and longitude around a globe. 


Slices 


rt ote 


Stacks 


FIGURE 10.3 A quadric sphere’s stacks and slices. 


The quadric spheres are drawn on their sides with the positive z-axis pointing out the top 
of the spheres. Figure 10.4 shows a wireframe quadric sphere drawn around the unit axes. 


Cylinders are also drawn along the positive z-axis and are composed of a number of 
stacked strips. The following function, which is similar to the gluSphere function, draws a 
cylinder: 


void gluCylinder(GLUquadricObj *obj, GLdouble baseRadius, 
GLdouble topRadius, GLdouble height, 
GLint slices, GLint stacks); 


With this function, you can specify both the base radius (near the origin) and the top 
radius (out along positive z-axis). The height parameter is simply the length of the cylin- 
der. The orientation of the cylinder is shown in Figure 10.5. Figure 10.6 shows the same 
cylinder, but with the topRadius parameter set to 0, making a cone. 
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FIGURE 10.4 A quadric sphere’s orientation. 


FIGURE 10.5 A quadric cylinder’s orientation. 
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FIGURE 10.6 A quadric cone made from a cylinder. 


The final quadric surface is the disk. Disks are drawn with loops of quads or triangle strips, 
divided into some number of slices. You use the following function to render a disk: 


void gluDisk(GLUquadricObj *obj, GLdouble innerRadius, 
GLdouble outerRadius,GLint slices, GLint loops); 


To draw a disk, you specify both an inner radius and an outer radius. If the inner radius is 
0, you get a solid disk like the one shown in Figure 10.7. A nonzero radius gives you a disk 
with a hole in it, as shown in Figure 10.8. The disk is drawn in the xy plane. 


Modeling with Quadrics 

In the sample program SNOWMAN, all the quadric objects are used to piece together a 
crude model of a snowman. White spheres make up the three sections of the body. Two 
small black spheres make up the eyes, and an orange cone is drawn for the carrot nose. A 
cylinder is used for the body of a black top hat, and two disks, one closed and one open, 
provide the top and the rim of the hat. The output from SNOWMAN is shown in Figure 
10.9. Listing 10.1 shows the rendering code that draws the snowman by simply transform- 
ing the various quadric surfaces into their respective positions. 
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FIGURE 10.7 A quadric disk showing loops and slices. 


FIGURE 10.8 A quadric disk with a hole in the center. 
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LISTING 10.1 Rendering Code for the SNOWMAN Example 


void RenderScene(void) 


{ 
GLUquadricObj *p0bj; // Quadric Object 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 


// Save the matrix state and do the rotations 
glPushMatrix(); 
// Move object back and do in place rotation 
glTranslatef(0.0f, -1.0f, -5.0f); 
glRotatef(xRot, 1.0f, 0.0f, 0.0f); 
glRotatef(yRot, @.0f, 1.0f, 0.0f); 


// Draw something 
pObj = gluNewQuadric(); 
gluQuadricNormals(p0bj, GLU_SMOOTH) ; 


// Main Body 

glPushMatrix(); 
glColor3f(1.0f, 1.0f, 1.0f); 
gluSphere(pObj, .40f, 26, 13); // Bottom 


glTranslatef(0.0f, .550f, 0.0f); // Mid section 
gluSphere(pObj, .3f, 26, 13); 


glTranslatef(0.0f, 0.45f, 0.0f); // Head 
gluSphere(pObj, 0.24f, 26, 13); 


// Eyes 

glColor3f(@.0f, 0.0f, 0.0f); 
glTranslatef(0.1f, @.1f, 0.21f); 
gluSphere(pObj, 0.02f, 26, 13); 


glTranslatef(-@.2f, 0.0f, 0.0f); 
gluSphere(pObj, 0.02f, 26, 13); 


// Nose 
glColor3f(1.0f, 0.3f, 0.3f); 
glTranslatef(0.1f, -0.12f, 0.Of); 
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LISTING 10.1 Continued 


gluCylinder(pObj, 0.04f, 0.0f, @.3f, 26, 13); 
glPopMatrix(); 


// Hat 

glPushMatrix(); 
glColor3f(0.0f, @.0f, 0.0f); 
glTranslatef(0.0f, 1.17f, 0.0f); 
glRotatef(-90.0f, 1.0f, @.0f, 0.0f); 
gluCylinder(pObj, 0.17f, 0.17f, @.4f, 26, 13); 


// Hat brim 

glDisable(GL_CULL_FACE); 
gluDisk(pObj, @.17f, @.28f, 26, 13); 
glEnable(GL_CULL_FACE) ; 


glTranslatef(0.0f, 0.0f, 0.40f); 
gluDisk(pObj, 0.0f, 0.17f, 26, 13); 
glPopMatrix(); 


// Restore the matrix state 
glPopMatrix(); 


// Buffer swap 
glutSwapBuffers(); 
} 
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FIGURE 10.9 A snowman rendered from quadric objects. 


Bézier Curves and Surfaces 


Quadrics provide built-in support for some very simple surfaces easily modeled with alge- 
braic equations. Suppose, however, you want to create a curve or surface, and you don’t 
have an algebraic equation to start with. It’s far from a trivial task to figure out your 
surface in reverse, starting from what you visualize as the result and working down to a 
second- or third-order polynomial. Taking a rigorous mathematical approach is time 
consuming and error prone, even with the aid of a computer. You can also forget about 
trying to do it in your head. 
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Recognizing this fundamental need in the art of computer-generated graphics, Pierre 
Bézier, an automobile designer for Renault in the 1970s, created a set of mathematical 
models that could represent curves and surfaces by specifying only a small set of control 
points. In addition to simplifying the representation of curved surfaces, the models facili- 
tated interactive adjustments to the shape of the curve or surface. 


Other types of curves and surfaces and indeed a whole new vocabulary for computer- 
generated surfaces soon evolved. The mathematics behind this magic show are no more 
complex than the matrix manipulations in Chapter 4, “Geometric Transformation: The 
Pipeline,” and an intuitive understanding of these curves is easy to grasp. As we did in 
Chapter 4, we take the approach that you can do a lot with these functions without a 
deep understanding of their mathematics. 


Parametric Representation 

A curve has a single starting point, a length, and an endpoint. It’s really just a line that 
squiggles about in 3D space. A surface, on the other hand, has width and length and thus 
a surface area. We begin by showing you how to draw some smooth curves in 3D space 
and then extend this concept to surfaces. First, let’s establish some common vocabulary 
and math fundamentals. 


When you think of straight lines, you might think of this famous equation: 


y=mx+b 


Here, m equals the slope of the line, and b is the y intercept of the line (the place where 
the line crosses the y-axis). This discussion might take you back to your eighth-grade 
algebra class, where you also learned about the equations for parabolas, hyperbolas, expo- 
nential curves, and so on. All these equations expressed y (or x) in terms of some function 
of x (or y). 


Another way of expressing the equation for a curve or line is as a parametric equation. A 
parametric equation expresses both x and y in terms of another variable that varies across 
some predefined range of values that is not explicitly a part of the geometry of the curve. 
Sometimes in physics, for example, the x, y, and z coordinates of a particle might be in 
terms of some functions of time, where time is expressed in seconds. In the following, fi), 
&(), and h() are unique functions that vary with time (f): 


x= f(t) 


y=) 
z=h(t) 
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When we define a curve in OpenGL, we also define it as a parametric equation. The para- 
metric parameter of the curve, which we call u, and its range of values is the domain of 
that curve. Surfaces are described using two parametric parameters: u and v. Figure 10.10 
shows both a curve and a surface defined in terms of u and v domains. The important 
point to realize here is that the parametric parameters (u and v) represent the extents of 
the equations that describe the curve; they do not reflect actual coordinate values. 


1 x ={(u) Z x = flu,v) 
y=g(u) y=flu,v) 
z=h(u) z=f(u,v) 


FIGURE 10.10 Parametric representation of curves and surfaces. 


Control Points 

A curve is represented by a number of control points that influence the shape of the curve. 
For a Bézier curve, the first and last control points are actually part of the curve. The other 
control points act as magnets, pulling the curve toward them. Figure 10.11 shows some 
examples of this concept, with varying numbers of control points. 
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FIGURE 10.11 How control points affect curve shape. 
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The order of the curve is represented by the number of control points used to describe its 
shape. The degree is one less than the order of the curve. The mathematical meaning of 
these terms pertains to the parametric equations that exactly describe the curve, with the 
order being the number of coefficients and the degree being the highest exponent of the 
parametric parameter. If you want to read more about the mathematical basis of Bézier 
curves, see Appendix A, “Further Reading.” 


The curve in Figure 10.11(b) is called a quadratic curve (degree 2), and Figure 10.11(c) is 
called a cubic (degree 3). Cubic curves are the most typical. Theoretically, you could define 
a curve of any order, but higher order curves start to oscillate uncontrollably and can vary 
wildly with the slightest change to the control points. 


Continuity 

If two curves placed side by side share an endpoint (called the breakpoint), they together 
form a piecewise curve. The continuity of these curves at this breakpoint describes how 
smooth the transition is between them. The four categories of continuity are none, posi- 
tional (CO), tangential (C1), and curvature (C2). 


As you can see in Figure 10.12, no continuity occurs when the two curves don’t meet at 
all. Positional continuity is achieved when the curves at least meet and share a common 
endpoint. Tangential continuity occurs when the two curves have the same tangent at the 
breakpoint. Finally, curvature continuity means the two curves’ tangents also have the 
same rate of change at the breakpoint (thus an even smoother transition). 


; Tangent 
ovis = 
cant 
None C0-Positional 
C1-Tangent 
C2-Curvature 


FIGURE 10.12 Continuity of piecewise curves. 


When assembling complex surfaces or curves from many pieces, you usually strive for 
tangential or curvature continuity. You’ll see later that some parameters for curve and 
surface generation can be chosen to produce the desired continuity. 
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Evaluators 


OpenGL contains several functions that make it easy to draw Bézier curves and surfaces. 
To draw them, you specify the control points and the range for the parametric u and v 
parameters. Then, by calling the appropriate evaluation function (the evaluator), OpenGL 
generates the points that make up the curve or surface. We start with a 2D example of a 
Bézier curve and then extend it to three dimensions to create a Bézier surface. 


A 2D Curve 

The best way to start is to go through an example, explaining it line by line. Listing 10.2 
shows some code from the sample program BEZIER in this chapter’s subdirectory on the 
CD. This program specifies four control points for a Bézier curve and then renders the 
curve using an evaluator. The output from Listing 10.2 is shown in Figure 10.13. 


FIGURE 10.13 Output from the BEZIER sample program. 


LISTING 10.2 Code from BEZIER That Draws a Bézier Curve with Four Control Points 


// The number of control points for this curve 
GLint nNumPoints = 4; 


GLfloat ctrlPoints[4][3]= {{ -4.0f, 0.0f, 0.0f}, // End Point 
{ -6.0f, 4.0f, 0.0f}, // Control Point 
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LISTING 10.2 Continued 


{ 6.0f, -4.0f, 0.0f}, // Control Point 
{ 4.0f, 0.0f, @.0f }};  // End Point 


// This function is used to superimpose the control points over the curve 
void DrawPoints(void) 
{ 


int 25 // Counting variable 


// Set point size larger to make more visible 
glPointSize(5.0f); 


// Loop through all control points for this example 
glBegin(GL_POINTS) ; 
for(i = 0; i < nNumPoints; i++) 
glVertex2fv(ctrlPoints[i]); 
glEnd(); 
} 


// Called to draw scene 
void RenderScene(void) 
{ 


ant 23 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Sets up the bezier 

// This actually only needs to be called once and could go in 
// the setup function 

glMap1f(GL_MAP1_VERTEX_3, // Type of data generated 


Q.0f, // Lower u range 

100.0f, // Upper u range 

3, // Distance between points in the data 
nNumPoints, // number of control points 
&ctrlPoints[0][0]); // array of control points 


// Enable the evaluator 
glEnable(GL_MAP1_VERTEX_3) ; 


// Use a line strip to “connect -the-dots" 
glBegin(GL_LINE STRIP); 
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LISTING 10.2 Continued 
for(i = @; i <= 100; i++) 
{ 
// Evaluate the curve at this point 
glEvalCoordif((GLfloat) i); 


} 
glEnd(); 


// Draw the Control Points 
DrawPoints(); 


// Flush drawing commands 
glutSwapBuffers(); 
} 


// This function does any needed initialization on the rendering 
// context. 
void SetupRC() 

{ 

// Clear Window to white 

glClearColor(1.0f, 1.0f, 1.0f, 1.0f ); 


// Draw in Blue 
glColor3f(@.0f, @.0f, 1.0f); 
} 


FETTTTTTTT TTT TTT TT 
// Set 2D Projection 
void ChangeSize(int w, int h) 


{ 
// Prevent a divide by zero 
if(h == Q) 


h= 1; 


// Set Viewport to window dimensions 
glViewport(®, @, w, h); 

glMatrixMode (GL_PROJECTION) ; 
glLoadidentity(); 


gluOrtho2D(-10.0f, 10.0f, -10.0f, 10.0f); 


// Modelview matrix reset 
glMatrixMode(GL_MODELVIEW) ; 
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LISTING 10.2 Continued 


glLoadIdentity(); 
} 


The first thing we do in Listing 10.2 is define the control points for our curve: 


// The number of control points for this curve 
GLint nNumPoints = 4; 


GLfloat ctrlPoints[4][3]= {{ -4.0f, 0.0f, 0.0f}, // Endpoint 
{ -6.0f, 4.0f, 0.0f}, // Control point 
{ 6.0f, -4.0f, 0.0f}, // Control point 
{ 4.0f, @.0f, @.0f }};  // Endpoint 


We defined global variables for the number of control points and the array of control 
points. To experiment, you can change them by adding more control points or just modi- 
fying the position of these points. 


The DrawPoints function is reasonably straightforward. We call this function from our 
rendering code to display the control points along with the curve. This capability also is 
useful when you're experimenting with control-point placement. Our standard 
ChangeSize function establishes a 2D orthographic projection that spans from -10 to +10 
in the x and y directions. 


Finally, we get to the rendering code. The RenderScene function first calls g1Map1f (after 
clearing the screen) to create a mapping for our curve: 


// Called to draw scene 
void RenderScene(void) 
{ 


inte; 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Sets up the Bezier 

// This actually only needs to be called once and could go in 
// the setup function 

glMap1f (GL_MAP1_VERTEX_3, // Type of data generated 


Q.0f, // Lower u range 
100.0f, // Upper u range 
3, // Distance between points in the data 


nNumPoints, // Number of control points 


Bézier Curves and Surfaces 


&ctrlPoints[][®]); // Array of control points 


The first parameter to glMap1f, GL_MAP1_VERTEX_3, sets up the evaluator to generate vertex 
coordinate triplets (x, y, and z). You can also have the evaluator generate other values, 
such as texture coordinates and color information. See the reference section at the end of 
this chapter for details. 


The next two parameters specify the lower and upper bounds of the parametric u value for 
this curve. The lower value specifies the first point on the curve, and the upper value spec- 
ifies the last point on the curve. All the values in between correspond to the other points 
along the curve. Here, we set the range to 0-100. 


The fourth parameter to glMap1f specifies the number of floating-point values between 
the vertices in the array of control points. Each vertex consists of three floating-point 
values (for x, y, and z), so we set this value to 3. This flexibility allows the control points 
to be placed in an arbitrary data structure, as long as they occur at regular intervals. 


The last parameter is a pointer to a buffer containing the control points used to define the 
curve. Here, we pass a pointer to the first element of the array. After creating the mapping 
for the curve, we enable the evaluator to make use of this mapping. This capability is 
maintained through a state variable, and the following function call is all that is needed to 
enable the evaluator to produce points along the curve: 


// Enable the evaluator 
glEnable(GL_MAP1_VERTEX_3) ; 


The glEvalCoord1f function takes a single argument: a parametric value along the curve. 
This function then evaluates the curve at this value and calls g1Vertex internally for that 
point. By looping through the domain of the curve and calling glEvalCoord to produce 
vertices, we can draw the curve with a simple line strip: 


// Use a line strip to "connect the dots" 
glBegin(GL_LINE_ STRIP) ; 
for(i = 0; i <= 100; i++) 
{ 
// Evaluate the curve at this point 
glEvalCoordif((GLfloat) i); 
} 
glEnd(); 


Finally, we want to display the control points themselves: 


// Draw the control points 
DrawPoints(); 
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Evaluating a Curve 

OpenGL can make things even easier than what we’ve done so far. We set up a grid with 
the glMapGrid function, which tells OpenGL to create an evenly spaced grid of points over 
the u domain (the parametric argument of the curve). Then we call glEvalMesh to 
“connect the dots” using the primitive specified (GL_LINE or GL_POINTS). The two 

function calls 


// Use higher level functions to map to a grid, then evaluate the 
// entire thing. 


// Map a grid of 100 points from @ to 100 
glMapGridid(100,0.0,100.0); 


// Evaluate the grid, using lines 
glEvalMesh1 (GL_LINE,@, 100) ; 


completely replace the code 


// Use a line strip to "“connect-the-dots" 
glBegin(GL_LINE_STRIP); 
for(i = 0; i <= 100; i++) 
{ 
// Evaluate the curve at this point 
glEvalCoordif((GLfloat) i); 
} 
glEnd(); 


As you can see, this approach is more compact and efficient, but its real benefit comes 
when evaluating surfaces rather than curves. 


A 3D Surface 

Creating a 3D Bézier surface is much like creating the 2D version. In addition to defining 
points along the u domain, we must define them along the v domain. Listing 10.3 
contains code from our next sample program, BEZ3D, and displays a wire mesh of a 3D 
Bézier surface. The first change from the preceding example is that we have defined three 
more sets of control points for the surface along the v domain. To keep this surface simple, 
we've kept the same control points except for the z value. This way, we create a uniform 
surface, as if we simply extruded a 2D Bézier along the z-axis. 


LISTING 10.3 BEZ3D Code to Create a Bézier Surface 


// The number of control points for this curve 
GLint nNumPoints = 3; 
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LISTING 10.3 Continued 

GLfloat ctrlPoints[3][3][S3]= {{{ -4.0f, 0.0f, 4.0f}, 
{ -2.0f, 4.0f, 4.0f}, 
{ 4.0f, 0.0f, 4.O0f }}, 


{{ -4.0f, 0.0f, 0.0f}, 
{ -2.0f, 4.0f, 0.0f}, 
{ 4.0f, 0.0f, 0.0f }}, 


{{ -4.0f, 0.0f, -4.0f}, 
{ -2.0f, 4.0f, -4.0f}, 
{ 4.0f, O.0f, -4.0f }}}; 


// This function is used to superimpose the control points over the curve 
void DrawPoints(void) 


{ 
inte, Ts // Counting variables 


// Set point size larger to make more visible 
glPointSize(5.0f) ; 


// Loop through all control points for this example 
glBegin(GL_POINTS) ; 
for(i = 0; i < nNumPoints; i++) 
POR :2 03) J < 33 eh) 
glVertex3fv(ctrlPoints[i][j]); 
glEnd(); 
} 


// Called to draw scene 

void RenderScene(void) 
{ 
// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Save the modelview matrix stack 
glMatrixMode (GL_MODELVIEW) ; 
glPushMatrix() ; 
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// Rotate the mesh around to make it easier to see 
glRotatef(45.0f, @.0f, 1.0f, 0.0f); 
glRotatef(60.0f, 1.0f, 0.0f, 0.Of); 
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LISTING 10.3 Continued 


// Sets up the Bezier 
// This actually only needs to be called once and could go in 
// the setup function 


glMap2f (GL_MAP2_VERTEX_3, // Type of data generated 

Q.0f, // Lower u range 

10.0f, // Upper u range 

3, // Distance between points in the data 
3, // Dimension in u direction (order) 
Q.0f, // Lover v range 

10.0f, // Upper v range 

9, // Distance between points in the data 
3, // Dimension in v direction (order) 
&ctrlPoints[0][0][®]); // array of control points 


// Enable the evaluator 
glEnable(GL_MAP2_VERTEX_3) ; 


// Use higher level functions to map to a grid, then evaluate the 
// entire thing. 


// Map a grid of 10 points from @ to 10 
glMapGrid2f(10,0.0f,10.0f,10,0.0f,10.0f); 


// Evaluate the grid, using lines 
glEvalMesh2(GL_LINE,0,10,0,10); 


// Draw the Control Points 
DrawPoints(); 


// Restore the modelview matrix 
glPopMatrix(); 


// Display the image 
glutSwapBuffers() ; 
} 


Our rendering code is different now, too. In addition to rotating the figure for a better 
visual effect, we call g1Map2f instead of g1Map1f. This call specifies control points along 
two domains (u and v) instead of just one (u): 
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// Sets up the Bezier 

// This actually only needs to be called once and could go in 
// the setup function 

glMap2f (GL_MAP2_VERTEX_3, // Type of data generated 


Q.0f, // Lower u range 

10.0f, // Upper u range 

3, // Distance between points in the data 
3, // Dimension in u direction (order) 
Q.0f, // Lower v range 

10.0f, // Upper v range 

9, // Distance between points in the data 
3, // Dimension in v direction (order) 
&ctrlPoints[0][0][@]); // Array of control points 


We must still specify the lower and upper range for u, and the distance between points in 
the u domain is still 3. Now, however, we must also specify the lower and upper range in 
the v domain. The distance between points in the v domain is now nine values because 
we have a three-dimensional array of control points, with each span in the u domain 
being three points of three values each (3 x 3 = 9). Then we tell glMap2f how many points 
in the v direction are specified for each u division, followed by a pointer to the control 
points themselves. 


The two-dimensional evaluator is enabled just like the one-dimensional version, and we 
call glMapGrid2f with the number of divisions in the u and v direction: 


// Enable the evaluator 
glEnable(GL_MAP2_VERTEX_3) ; 


// Use higher level functions to map to a grid, then evaluate the 
// entire thing. 


// Map a grid of 10 points from @ to 10 
glMapGrid2f (10,0.0f ,10.0f,10,0.0f ,10.0F); 


After the evaluator is set up, we can call the two-dimensional (meaning u and v) version 
of glEvalMesh to evaluate our surface grid. Here, we evaluate using lines and specify the u 
and v domains’ values to range from 0 to 10: 


// Evaluate the grid, using lines 
glEvalMesh2(GL_LINE,0,10,0,10); 


The result is shown in Figure 10.14. 
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FIGURE 10.14 Output from the BEZ3D program. 


Lighting and Normal Vectors 
Another valuable feature of evaluators is the automatic generation of surface normals. By 
simply changing this code 


// Evaluate the grid, using lines 

glEvalMesh2(GL_LINE,®,10,0,10) ; 

to this 

// Evaluate the grid, using lines 

glEvalMesh2(GL_FILL,0,10,0, 10); 

and then calling 

glEnable(GL_AUTO_NORMAL) ; 

in our initialization code, we enable easy lighting of surfaces generated by evaluators. 
Figure 10.15 shows the same surface as Figure 10.14, but with lighting enabled and auto- 
matic normalization turned on. The code for this program appears in the BEZLIT sample 


in the CD subdirectory for this chapter. The program is only slightly modified from 
BEZ3D. 
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FIGURE 10.15 Output from the BEZLIT program. 


NURBS 


You can use evaluators to your heart’s content to evaluate Bézier surfaces of any degree, 
but for more complex curves, you have to assemble your Béziers piecewise. As you add 
more control points, creating a curve that has good continuity becomes difficult. A higher 
level of control is available through the GLU library’s NURBS functions. NURBS stands for 
non-uniform rational B-spline. Mathematicians out there might know immediately that this 
is just a more generalized form of curves and surfaces that can produce Bézier curves and 
surfaces, as well as some other kinds (mathematically speaking). These functions allow you 
to tweak the influence of the control points you specified for the evaluators to produce 
smoother curves and surfaces with larger numbers of control points. 


From Bézier to B-Splines 

A Bézier curve is defined by two points that act as endpoints and any number of other 
control points that influence the shape of the curve. The three Bézier curves in Figure 
10.16 have three, four, and five control points specified. The curve is tangent to a line that 
connects the endpoints with their adjacent control points. For quadratic (three points) 
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and cubic (four points) curves, the resulting Béziers are quite smooth, usually with a conti- 
nuity of C2 (curvature). For higher numbers of control points, however, the smoothness 
begins to break down as the additional control points pull and tug on the curve. 


° Ps Py 
Third order Fourth order Fifth order 


FIGURE 10.16 Bézier continuity as the order of the curve increases. 


B-splines (bi-cubic splines), on the other hand, work much as the Bézier curves do, but the 
curve is broken down into segments. The shape of any given segment is influenced only 
by the nearest four control points, producing a piecewise assemblage of a curve with each 
segment exhibiting characteristics much like a fourth-order Bézier curve. A long curve with 
many control points is inherently smoother, with the junction between each segment 
exhibiting C2 continuity. It also means that the curve does not necessarily have to pass 
through any of the control points. 


Knots 


The real power of NURBS is that you can tweak the influence of the four control points for 
any given segment of a curve to produce the smoothness needed. This control is handled 
via a sequence of values called knots. Two knot values are defined for every control point. 
The range of values for the knots matches the u or v parametric domain and must be 
nondescending. The knot values determine the influence of the control points that fall 
within that range in u/v space. Figure 10.17 shows a curve demonstrating the influence of 
control points over a curve having four units in the u parametric domain. Points in the 
middle of the u domain have a greater pull on the curve, and only points between 0 and 3 
have any effect on the shape of the curve. 


The key here is that one of these influence curves exists at each control point along the 
u/v parametric domain. The knot sequence then defines the strength of the influence of 
points within this domain. If a knot value is repeated, points near this parametric value 
have even greater influence. The repeating of knot values is called knot multiplicity. Higher 
knot multiplicity decreases the curvature of the curve or surface within that region. 


NURBS 


FIGURE 10.17 Control point influence along the u parameter. 


Creating a NURBS Surface 

The GLU NURBS functions provide a useful high-level facility for rendering surfaces. You 
don’t have to explicitly call the evaluators or establish the mappings or grids. To render a 
NURBS, you first create a NURBS object that you reference whenever you call the NURBS- 
related functions to modify the appearance of the surface or curve. 


The gluNewNurbsRenderer function creates a renderer for the NURB, and 
gluDeleteNurbsRenderer destroys it. The following code fragments demonstrate these 
functions in use: 


// NURBS object pointer 
GLUnurbsObj *pNurb = NULL; 


// Setup the NURBS object 
pNurb = gluNewNurbsRenderer() ; 


// Do your NURBS things... 


// Delete the NURBS object if it was created 
if (pNurb) 
gluDeleteNurbsRenderer (pNurb) ; 
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NURBS Properties 
After you have created a NURBS renderer, you can set various high-level NURBS properties 
for the NURB: 


// Set sampling tolerance 
gluNurbsProperty(pNurb, GLU_SAMPLING TOLERANCE, 25.0f); 


// Fill to make a solid surface (use GLU_OUTLINE_POLYGON to create a 
// polygon mesh) 
gluNurbsProperty(pNurb, GLU_DISPLAY_MODE, (GLfloat)GLU_FILL); 


You typically call these functions in your setup routine rather than repeatedly in your 
rendering code. In this example, GLU_SAMPLING_TOLERANCE defines the fineness of the 
mesh that defines the surface, and GLU_FILL tells OpenGL to fill in the mesh instead of 
generating a wireframe. 


Defining the Surface 

The surface definition is passed as arrays of control points and knot sequences to the 
gluNurbsSurface function. As shown here, this function is also bracketed by calls to 
gluBeginSurface and gluEndSurface: 


// Render the NURB 
// Begin the NURB definition 
gluBeginSurface(pNurb) ; 


// Evaluate the surface 
gluNurbsSurface(pNurb, // Pointer to NURBS renderer 


8, Knots, // No. of knots and knot array u direction 
8, Knots, // No. of knots and knot array v direction 
Ah: &.Gi, // Distance between control points in u dir. 
3, // Distance between control points in v dir. 
&ctrlPoints[®][®][®],// Control points 

4, 4, // u and v order of surface 


GL_MAP2_VERTEX_3) ; // Type of surface 


// Done with surface 
gluEndSurface(pNurb) ; 


You can make more calls to gluNurbsSurface to create any number of NURBS surfaces, but 
the properties you set for the NURBS renderer are still in effect. Often, this is desired; you 
rarely want two surfaces (perhaps joined) to have different fill styles (one filled and one a 
wire mesh). 
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Using the control points and knot values shown in the next code segment, we produced 
the NURBS surface shown in Figure 10.18. You can find this NURBS program in this 
chapter’s subdirectory on the CD: 


// Mesh extends four units -6 to +6 along x and y axis 
// Lies in Z plane 


// uo Vv #(xXpeeze 
GLfloat ctrlPoints[4](4](3]= {{{ -6.0f, -6.0f, 0.0f}, /i/u=0, v=20 
{ -6.0f, -2.0f, 0.0f}, // v=1 
{ -6.0f, 2.0f, 0.0f}, // via2 
{ -6.0f, 6.0f, @.0f}}, // v=3 
{{ -2.0f, -6.0f, 0.0f}, /i/ u=1 v=0 
{2 20F,-- -2 Of ,* 8508}, 1/ v=1 
(or 2.Of 2. Of 8 .Ofhiac 17 V =:2 
{ -2.0f, 6.0f, @.0f}}, // v=3 
Lhe 240F 5258 0F 07 0fE} 5. 2) fu <2 v= 0 
{ 2.0f, -2.0f, 8.0f }, // a 
{ 2;0f)--2.0f,) 8.80}, <7 / v=2 
{ 2.0f, 6.0f, 0.0f }}, // Ves 
{{ 6.0f, -6.0f, 0.0f}, // u=83 v=0 
{ 6.0f, -2.0f, 0.0f}, // v=1 
{ 6.0f, 2.0f, @.0f}, // yi sme 
{ 6.0f, 6.O0f, O.Of}}}; // v=3 


// Knot sequence for the NURB 
GLfloat Knots[8] = {@.0f, O.0f, O.Of, O.0f, 1.0f, 1.0f, 1.0f, 1.0f}; 


Trimming 

Trimming means creating cutout sections from NURBS surfaces. This capability is often 
used for literally trimming sharp edges of a NURBS surface. You can also create holes in 
your surface just as easily. The output from the NURBT program is shown in Figure 10.19. 
This is the same NURBS surface used in the preceding sample (without the control points 
shown), with a triangular region removed. This program, too, is on the CD. 


Listing 10.4 shows the code added to the NURBS sample program to produce this trim- 
ming effect. Within the gluBeginSurface/gluEndSurface delimiters, we call gluBeginTrim, 
specify a trimming curve with gluPwlCurve, and finish the trimming curve with 
gluEndTrim. 
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FIGURE 10.18 Output from the NURBS program. 


FIGURE 10.19 Output from the NURBT program. 


NURBS 


LISTING 10.4 Modifications to NURBS to Produce Trimming 


// Outside trimming points to include entire surface 
GLfloat outsidePts[5][2] = /* counterclockwise */ 
{{Q.0f, O.0f}, {1.0f, O.Of}, {1.Of, 1.0f}, {O.0f, 1.0f}, {@.Of, 0.O0F}}; 


// Inside trimming points to create triangle shaped hole in surface 
GLfloat insidePts[4][2] = /* clockwise */ 
{{@.25f, 0.25f}, {0.5f, O.5f}, {0.75f, @.25f}, { 0.25f, 0.25f}}; 


// Render the NURB 
// Begin the NURB definition 
gluBeginSurface(pNurb) ; 


// Evaluate the surface 
gluNurbsSurface(pNurb, // Pointer to NURBS renderer 


8, Knots, // No. of knots and knot array u direction 
8, Knots, // No. of knots and knot array v direction 
44 3; // Distance between control points in u dir. 
3, // Distance between control points in v dir. 
&ctrlPoints[®][0][@],// Control points 

4, 4, // u and v order of surface 


GL_MAP2_VERTEX_3); // Type of surface 


// Outer area, include entire curve 

gluBeginTrim (pNurb) ; 

gluPwlCurve (pNurb, 5, &outsidePts[@][0], 2, GLU_MAP1_TRIM_2); 
gluEndTrim (pNurb); 


// Inner triangular area 

gluBeginTrim (pNurb) ; 

gluPwlCurve (pNurb, 4, &insidePts[®][@], 2, GLU_MAP1_TRIM_2); 
gluEndTrim (pNurb) ; 


// Done with surface 
gluEndSurface(pNurb) ; 


Within the gluBeginTrim/gluEndTrim delimiters, you can specify any number of curves as 
long as they form a closed loop in a piecewise fashion. You can also use gluNurbsCurve to 
define a trimming region or part of a trimming region. These trimming curves must, 
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however, be in terms of the unit parametric u and v space. This means the entire u/v 
domain is scaled from 0.0 to 1.0. 


gluPwlCurve defines a piecewise linear curve--nothing more than a list of points 
connected end to end. In this scenario, the inner trimming curve forms a triangle, but 
with many points, you could create an approximation of any curve needed. 


Trimming a curve trims away surface area that is to the right of the curve’s winding. Thus, 
a clockwise-wound trimming curve discards its interior. Typically, an outer trimming curve 
is specified, which encloses the entire NURBS parameter space. Then smaller trimming 
regions are specified within this region with clockwise winding. Figure 10.20 illustrates 
this relationship. 


FIGURE 10.20 An area inside clockwise-wound curves is trimmed away. 


NURBS Curves 


Just as you can have Bézier surfaces and curves, you can also have NURBS surfaces and 
curves. You can even use gluNurbsCurve to do NURBS surface trimming. By this point, we 
hope you have the basics down well enough to try trimming surfaces on your own. 
However, another sample, NURBC, is included on the CD if you want a starting point to 
play with. 


Tessellation 


To keep OpenGL as fast as possible, all geometric primitives must be convex. We made this 
point in Chapter 3, “Drawing in Space: Geometric Primitives and Buffers.” However, many 
times we have vertex data for a concave or more complex shape that we want to render 
with OpenGL. These shapes fall into two basic categories, as shown in Figure 10.21. A 
simple concave polygon is shown on the left, and a more complex polygon with a hole in 
it is shown on the right. For the shape on the left, you might be tempted to try using 
GL_POLYGON as the primitive type, but the rendering would fail because OpenGL algorithms 
are optimized for convex polygons. As for the figure on the right...well, there is little hope 
for that shape at all! 


Tessellation 


Concave Complex 


FIGURE 10.21 Some nonconvex polygons. 
The intuitive solution to both of these problems is to break down the shape into smaller 


convex polygons or triangles that can be fit together to create the final overall shape. 
Figure 10.22 shows one possible solution to breaking the shapes in Figure 10.21 into more 


manageable triangles. 


FIGURE 10.22 Complex shapes broken down into triangles. 


Breaking down the shapes by hand is tedious at best and possibly error prone. Fortunately, 
the OpenGL Utility Library contains functions to help you break concave and complex 
polygons into smaller, valid OpenGL primitives. The process of breaking down these poly- 
gons is called tessellation. 


The Tessellator 
Tessellation works through a tessellator object that must be created and destroyed much in 
the same way that we did for quadric state objects: 


GLUtesselator *pTess; 
pTess = gluNewTes(); 
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// Do some tessellation 
gluDeleteDess(pTess) ; 


All the tessellation functions use the tessellator object as the first parameter. This allows 
you to have more than one tessellation object active at a time or interact with libraries or 
other code that also uses tessellation. The tessellation functions change the tessellator’s 
state and behavior, and this allows you to make sure your changes affect only the object 
you are currently working with. Alas, yes, GLUtesselator has only one / and is thus 
misspelled! 


The tessellator breaks up a polygon and renders it appropriately when you perform the 
following steps: 


1. Create the tessellator object. 

Set tessellator state and callbacks. 

Start a polygon. 

Start a contour. 

Feed the tessellator the vertices that specify the contour. 
End the contour. 


Go back to step 4 if there are more contours. 


PS oer ee eis 


End the polygon. 


Each polygon consists of one or more contours. The polygon to the left in Figure 10.21 
contains one contour, simply the path around the outside of the polygon. The polygon on 
the right, however, has two contours: the outside edge and the edge around the inner 
hole. Polygons may contain any number of contours (several holes) or even nested 
contours (holes within holes). The actual work of tessellating the polygon does not occur 
until step 8. This task can sometimes be very time consuming, and if the geometry is 
static, it may be best to store these function calls in a display list (the next chapter 
discusses display lists). 


Tessellator Callbacks 


During tessellation, the tessellator calls a number of callback functions that you must 
provide. You use these callbacks to actually specify the vertex information and begin and 
end the primitives. The following function registers the callback functions: 


void gluTessCallback(GLUTesselator *tobj, GLenum which, void (*fn)()); 
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The first parameter is the tessellation object. The second specifies the type of callback 
being registered, and the last is the pointer to the callback function itself. You can specify 
various callbacks, which are listed in Table 10.3 in the reference section. As an example, 
examine the following lines of code: 


// Just call glBegin at beginning of triangle batch 
gluTessCallback(pTess, GLU_TESS BEGIN, glBegin); 


// Just call glEnd at end of triangle batch 
gluTessCallback(pTess, GLU_TESS_END, glEnd); 


// Just call glVertex3dv for each vertex 
gluTessCallback(pTess, GLU_TESS_VERTEX, glVertex3dv) ; 


The GLU_TESS_BEGIN callback specifies the function to call at the beginning of each new 
primitive. Specifying glBegin simply tells the tessellator to call g1Begin to begin a primi- 
tive batch. This may seem pointless, but you can also specify your own function here to 
do additional processing whenever a new primitive begins. For example, suppose you 
want to find out how many triangles are used in the final tessellated polygon. 


The GLU_TESS_END callback, again, simply tells the tessellator to call glEnd and that you 
have no other specific code you want to inject into the process. Finally, the 
GLU_TESS_VERTEX call drops in a call to glVertex3dv to specify the tessellated vertex data. 
Tessellation requires that vertex data be specified as double precision, and always uses 
three component vertices. Again, you could substitute your own function here to do some 
additional processing (such as adding color, normal, or texture coordinate information). 


For an example of specifying your own callback (instead of cheating and just using exist- 
ing OpenGL functions), the following code shows the registration of a function to report 
any errors that may occur during tessellation: 


FLTTTTTTT TATA TTT TTT TAA TTT TAT A 
// Tessellation error callback 
void tessError(GLenum error) 

{ 

// Get error message string 

const char *szError = gluErrorString(error) ; 


// Set error message as window caption 
glutSetWindowTitle(szError) ; 
} 
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// Register error callback 
gluTessCallback(pTess, GLU_TESS ERROR, tessError); 


Specifying Vertex Data 
To begin a polygon (this corresponds to step 3 shown earlier), you call the following func- 
tion: 


void gluTessBeginPolygon(GLUTesselator *tobj, void *data); 


You first pass in the tessellator object and then a pointer to any user-defined data that you 
want associated with this tessellation. This data can be sent back to you during tessellation 
using the callback functions listed in Table 10.3. Often, this is just NULL. To finish the 
polygon (step 8) and begin tessellation, call this function: 


void gluTessEndPolygon(GLUTesselator *tobj); 


Nested within the beginning and ending of the polygon, you specify one or more 
contours using the following pair of functions (steps 4 and 6): 


void gluTessBeginContour(GLUTesselator *tobj); 
void gluTessEndContour(GLUTesselator *tobj); 


Finally, within the contour, you must add the vertices that make up that contour (step 5). 
The following function feeds the vertices, one at a time, to the tessellator: 


void gluTessVertex(GLUTesselator *tobj, GLdouble v[3], void *data); 


The v parameter contains the actual vertex data used for tessellator calculations. The data 
parameter is a pointer to the vertex data passed to the callback function specified by 
GLU_VERTEX. Why two different arguments to specify the same thing? Because the pointer 
to the vertex data may also point to additional information about the vertex (color, 
normals, and so on). If you specify your own function for GLU_VERTEX (instead of our 
cheat), you can access this additional vertex data in the callback routine. 


Putting It All Together 


Now let’s look at an example that takes a complex polygon and performs tessellation to 
render a solid shape. The sample program FLORIDA contains the vertex information to 
draw the crude, but recognizable, shape of the state of Florida. The program has three 
modes of rendering, accessible via the context menu: Line Loops, Concave Polygon, and 
Complex Polygon. The basic shape with Line Loops is shown in Figure 10.23. 


FIGURE 10.23 Basic outline of Florida. 


Tessellation 


Listing 10.5 shows the vertex data and the rendering code that draws the outlines for the 


state and Lake Okeechobee. 


LISTING 10.5 Vertex Data and Drawing Code for State Outline 


// Coast Line Data 
#define COAST_POINTS 24 


GLdouble vCoast[COAST_POINTS][3] = {{- 
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LISTING 10.5 Continued 


{-12.0, 5.0, 0.0 }, 
{-20.0, 10.0, 0.0 }, 
{-30.0, 20.0, 0.0 }, 
{-40.0, 15.0, 0.0 }, 
{-50.0, 15.0, 0.0 }, 
{-55.0, 20.0, 0.0 }, 
{-60.0, 25.0, 0.0 }, 
{-70.0, 25.0, 0.0 }}; 


// Lake Okeechobee 

#define LAKE POINTS 4 

GLdouble vLake[LAKE_POINTS][3] = {{ 10.0, -20.0, 0.0 }, 
{ 15.0, -25.0, 0.0 }, 
{ 10.0, -30.0, 0.0 }, 
{ 5.0, -25.0, 0.0 }}; 


case DRAW_LOOPS: // Draw line loops 


{ 
glColor3f(@.0f, 0.0f, 0.0f); // Just black outline 


// Line loop with coastline shape 

glBegin(GL_LINE_LOOP) ; 

for(i = 0; i < COAST_POINTS; i++) 
glVertex3dv(vCoast[i]); 

glEnd(); 


// Line loop with shape of interior lake 

glBegin(GL_LINE_LOOP) ; 

for(i = 0; i < LAKE_POINTS; it+) 
glVertex3dv(vLake[i]); 

glEnd(); 


} 
break; 


For the Concave Polygon rendering mode, only the outside contour is drawn. This results 
in a solid filled shape, despite the fact that the polygon is clearly concave. This result is 
shown in Figure 10.24, and the tessellation code is shown in Listing 10.6. 
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FIGURE 10.24 A solid convex polygon. 


LISTING 10.6 Drawing a Convex Polygon 


case DRAW CONCAVE: // Tessellate concave polygon 
{ 
// Tessellator object 
GLUtesselator *pTess; 


// Green polygon 
glColor3f(0.0f, 1.0f, 0.0f); 


// Create the tessellator object 
pTess = gluNewTess(); 


// Set callback functions 
// Just call glBegin at beginning of triangle batch 
gluTessCallback(pTess, GLU_TESS_BEGIN, glBegin) ; 


// Just call glEnd at end of triangle batch 
gluTessCallback(pTess, GLU_TESS_END, glEnd); 


// Just call glVertex3dv for each vertex 
gluTessCallback(pTess, GLU_TESS_VERTEX, glVertex3dv) ; 
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LISTING 10.6 Continued 


// Register error callback 
gluTessCallback(pTess, GLU_TESS_ERROR, tessError) ; 


// Begin the polygon 
gluTessBeginPolygon(pTess, NULL); 


// Begin the one and only contour 
gluTessBeginContour (pTess) ; 


// Feed in the list of vertices 
for(i = 0; i < COAST_POINTS; i++) 
gluTessVertex(pTess, vCoast[i], vCoast[i]); // Can't be NULL 


// Close contour and polygon 
gluTessEndContour(pTess) ; 
gluTessEndPolygon(pTess) ; 


// All done with tessellator object 
gluDeleteTess(pTess) ; 
} 


break; 


Finally, we present a more complex polygon, one with a hole in it. The Complex Polygon 
drawing mode draws the solid state, but with a whole representing Lake Okeechobee (a 
large lake in south Florida, typically shown on maps). The output is shown in Figure 
10.25, and the relevant code is presented in Listing 10.7. 


LISTING 10.7 Tessellating a Complex Polygon with Multiple Contours 


case DRAW_COMPLEX: // Tessellate, but with hole cut out 
if 


// Tessellator object 
GLUtesselator *pTess; 


// Green polygon 
glColor3f(0.0f, 1.0f, 0.0f); 


// Create the tessellator object 
pTess = gluNewTess(); 


// Set callback functions 
// Just call glBegin at beginning of triangle batch 
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LISTING 10.7 Continued 
gluTessCallback(pTess, GLU_TESS BEGIN, glBegin) ; 


// Just call glEnd at end of triangle batch 
gluTessCallback(pTess, GLU_TESS_END, glEnd); 


// Just call glVertex3dv for each vertex 
gluTessCallback(pTess, GLU_TESS_VERTEX, glVertex3dv) ; 


// Register error callback 
gluTessCallback(pTess, GLU_TESS_ERROR, tessError) ; 


// How to count filled and open areas 
gluTessProperty(pTess, GLU_TESS_ WINDING RULE, GLU_TESS_WINDING_ODD) ; 


// Begin the polygon 
gluTessBeginPolygon(pTess, NULL); // No user data 


// First contour, outline of state 

gluTessBeginContour(pTess) ; 

for(i = 0; i < COAST_POINTS; i++) 
gluTessVertex(pTess, vCoast[i], vCoast[i]); 

gluTessEndContour(pTess) ; 


// Second contour, outline of lake 

gluTessBeginContour(pTess) ; 

for(i = 0; i < LAKE_POINTS; i++) 
gluTessVertex(pTess, vLake[i], vLake[i]}); 

gluTessEndContour(pTess) ; 


// All done with polygon 
gluTessEndPolygon(pTess) ; 


// No longer need tessellator object 
gluDeleteTess(pTess) ; 


} 
break; 


This code contained a new function call: 


// How to count filled and open areas 
gluTessProperty(pTess, GLU_TESS_WINDING_RULE, GLU_TESS_WINDING_ODD) ; 
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FIGURE 10.25 The solid polygon, but with a hole. 


This call tells the tessellator how to decide what areas to fill in and which areas to leave 
empty when there are multiple contours. The value GLU_TESS_WINDING_ODD is actually the 
default, and we could have skipped this function. However, you should understand how 
the tessellator handles nested contours. By specifying ODD, we are saying that any given 
point inside the polygon is filled in if it is enclosed in an odd number of contours. The 
area inside the lake (inner contour) is surrounded by two (an even number) contours and 
is left unfilled. Points outside the lake but inside the state boundary are enclosed by only 
one contour (an odd number) and are drawn filled. 


Summary 


The quadrics library makes creating a few simple surfaces (spheres, cylinders, disks, and 
cones) child’s play. Expanding on this concept into more advanced curves and surfaces 
could have made this chapter the most intimidating in the entire book. As you have seen, 
however, the concepts behind these curves and surfaces are not very difficult to under- 
stand. Appendix A suggests further reading if you want in-depth mathematical informa- 
tion or tips on creating NURBS-based models. 


Other examples from this chapter give you a good starting point for experimenting with 
NURBS. Adjust the control points and knot sequences to create warped or rumpled 
surfaces. Also, try some quadratic surfaces and some with higher order than the cubic 
surfaces. Watch out: One pitfall to avoid as you play with these curves is trying too hard 
to create one complex surface out of a single NURB. You can find greater power and flexi- 
bility if you compose complex surfaces out of several smaller and easy-to-handle NURBS or 
Bézier surfaces. 


Reference 


Finally, in this chapter, we saw OpenGL's powerful support for automatic polygon tessella- 
tion. You learned that you can draw complex surfaces, shapes, and patterns with only a 
few points that specify the boundaries. You also learned that concave regions and even 
regions with holes can be broken down into simpler convex primitives using the GLU 
library’s tessellator object. 


Reference 


glEvalCoord 


Purpose: Evaluates 1D and 2D maps that have been previously enabled. 
Include File: <gl.h> 
Variations: 


void glEvalCoordid(GLdouble u); 

void glEvalCoordif(GLfloat u); 

void glEvalCoord2d(GLdouble u, GLdouble v); 
void glEvalCoord2f(GLfloat u, GLfloat v); 
void glEvalCoordidv(const GLdouble *u); 
void glEvalCoordifv(const GLfloat *u); 

void glEvalCoord2dv(const GLdouble *u); 
void glEvalCoord2fv(const GLfloat *u); 


Description: This function uses a previously enabled evaluator (set up with g1Map) to 
produce vertex, color, normal, or texture values based on the parametric 
u/v values. The types of data and function calls simulated are specified by 
the glMap1 and glMap2 functions. 


Parameters: 

u,v These parameters specify the u and v parametric value that is to be evalu- 
ated along the curve or surface. 

Returns: None. 

See Also: glEvalMesh, glEvalPoint, glMap1, glMap2, glMapGrid 

glEvalMesh 

Purpose: Computes a 1D or 2D grid of points or lines. 


Include File: <gl.h> 
Variations: 


void glEvalMeshi(GLenum mode, GLint i7, GLint i2); 
void glEvalMesh2(GLenum mode, GLint i7, GLint i2, GLint j7, GLint j2); 
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Description: You use this function with glMapGrid to efficiently create a mesh of 
evenly spaced u and v domain values. glEvalMesh actually evaluates the 
mesh and produces the points, line segments, or filled polygons. 


Parameters: 

mode GLdouble: Specifies whether the mesh should be computed as points 
(GL_POINT), lines (GL_LINE), or filled meshes for surfaces (GL_FILL). 

di, t2 GLint: Specifies the first and last integer values for the u domain. 

jt, j2 GLint: Specifies the first and last integer values for the v domain. 

Returns: None. 

See Also: glBegin, glEvalCoord, glEvalPoint, glMap1, glMap2, g1lMapGrid 

glEvalPoint 

Purpose: Generates and evaluates a single point in a mesh. 


Include File: <gl.h> 
Variations: 


void glEvalPoint1(GLint i); 
void glEvalPoint2(GLint i, GLint j); 


Description: You can use this function in place of glEvalMesh to evaluate a domain at 
a single point. The evaluation produces a single primitive, GL_POINTS. 
The first variation (glEvalPoint1) is used for curves, and the second 
(glEvalPoint2) is for surfaces. 


Parameters: 

pA GLint: Specifies the u and v domain parametric values. 
Returns: None. 

See Also: glEvalCoord, glEvalMesh, glMap1, glMap2, g1MapGrid 
glGetMap 

Purpose: Returns evaluator parameters. 


Include File: <gl.h> 
Variations: 


void glGetMapdv(GLenum target, GLenum query, GLdouble *v); 
void glGetMapfv(GLenum target, GLenum query, GLfloat *v); 
void glGetMapiv(GLenum target, GLenum query, GLint *v); 


Description: 


Parameters: 
target 


query 


*y 


Returns: 
See Also: 


giMap 
Purpose: 
Include File: 
Variations: 


Reference 


This function retrieves map settings that were set by the g1Map functions. 
See g1Map1 and glMap2 in this section for explanations of the types of 
maps. 


GLenum: The name of the map; the following maps are defined: 
GL_MAP1_COLOR_4, GL_MAP1_INDEX, GL_MAP1_NORMAL, 
GL_MAP1_TEXTURE_COORD_1, GL_MAP1_TEXTURE_COORD_2, 
GL_MAP1_TEXTURE_COORD_3, GL_MAP1_TEXTURE_COORD_4, GL_MAP1_VERTEX_3, 
GL_MAP1_VERTEX_4, GL_MAP2_COLOR_4, GL_MAP2_INDEX, GL_MAP2_NORMAL, 
GL_MAP2_TEXTURE_COORD_1, GL_MAP2_TEXTURE_COORD 2, 
GL_MAP2_TEXTURE_COORD_3, GL_MAP2_TEXTURE_COORD_ 4, GL_MAP2_VERTEX_3, 
and GL_MAP2_VERTEX_4. See g1Map in this section for an explanation of 
these map types. 

GLenum: Specifies which map parameter to return in *v. It may be one of 
the following values: 

GL_COEFF: Returns an array containing the control points for the map. 
Coordinates are returned in row-major order. 1D maps return order 
control points, and 2D maps return u-order times the v-order control 
points. 

GL_ORDER: Returns the order of the evaluator function. For 1D maps, this 
is a single value. For 2D maps, two values are returned (an array) that 
contain first the u-order and then the v-order. 

GL_DOMAIN: Returns the linear parametric mapping parameters. For 1D 
evaluators, this is the lower and upper u value. For 2D maps, it’s the 
lower and upper u followed by the lower and upper v. 

Pointer to storage that will contain the requested parameter. The data 
type of this storage should match the function used (double, float, or 
integer). 

None. 

glEvalCoord, glMap1, glMap2 


Defines a 1D or 2D evaluator. 
<gl.h> 


void glMapid(GLenum target, GLdouble u7, GLdouble u2, 


GLint ustride, GLint uorder, 
const GlLdouble *points) ; 


void glMapif(GLenum target, GLfloat u7, GLfloat u2, 
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GLint ustride, GLint uorder, 
const GLfloat *points); 


void glMap2d(GLenum target, GLdouble u7, GLdouble u2, 


GLint ustride, GLint uvorder, 
GLdouble v7, GLdouble v2, 
GLint vstride, GLint vorder, 
const GLdouble *points); 


void glMap2f(GLenum target, GLfloat u7, GLfloat u2, 


Description: 


Parameters: 
target 


GLint ustride, GLint uorder, 
GLfloat v1, GLfloat v2, 
GLint vstride, GLint vorder, 
const GLfloat *points); 


These functions define 1D or 2D evaluators. The g1Map1x functions are 
used for 1D evaluators (curves), and the g1Map2x functions are used for 
2D evaluators (surfaces). Evaluators produce vertex or other information 
(see the target parameter) evaluated along one or two dimensions of a 
parametric range (u and v). 


GLenum: Specifies what kinds of values are produced by the evaluator. 
Valid values for 1D and 2D evaluators are as follows: 


GL_MAP1_VERTEX_3 (or GL_MAP2_VERTEX_3): Control points are three floats 
that represent x, y, and z coordinate values. glVertex3 commands are 
generated internally when the map is evaluated. 


GL_MAP1_VERTEX_4 (or GL_MAP2_VERTEX_4): Control points are four floats 
that represent x, y, z, and w coordinate values. g1Vertex4 commands are 
generated internally when the map is evaluated. 


GL_MAP1_INDEX (or GL_MAP2_INDEX): The generated control points are 
single floats that represent a color index value. glIndex commands are 
generated internally when the map is evaluated. Note: The current color 
index is not changed as it would be if glIndex were called directly. 


GL_MAP1_COLOR_4 (or GL_MAP2_COLOR_4): The generated control points are 
four floats that represent red, green, blue, and alpha components. 
glColor4 commands are generated internally when the map is evaluated. 
Note: The current color is not changed as it would be if g1Color4f were 
called directly. 


GL_MAP1_NORMAL (or GL_MAP2_NORMAL): The generated control points are 
three floats that represent the x, y, and z components of a normal vector. 
glNormal commands are generated internally when the map is evaluated. 
Note: The current normal is not changed as it would be if glNormal were 
called directly. 


ul, u2 
vi, v2 


ustride, 
vstride 


uorder, vorder 
*points 


Returns: 
See Also: 


glMapGrid 
Purpose: 
Include File: 


Reference 


GL_MAP1_TEXTURE_COORD_1 (or GL_MAP2_TEXTURE_COORD_1): The generated 
control points are single floats that represent the s texture coordinate. 
glTexCoord1 commands are generated internally when the map is evalu- 
ated. Note: The current texture coordinates are not changed as they 
would be if glTexCoord were called directly. 


GL_MAP1_TEXTURE_COORD_2 (or GL_MAP2_TEXTURE_COORD_2): The generated 
control points are two floats that represent the s and t texture coordi- 
nates. glTexCoord2 commands are generated internally when the map is 
evaluated. Note: The current texture coordinates are not changed as they 
would be if g1TexCoord were called directly. 


GL_MAP1_TEXTURE_COORD_3 (or GL_MAP2_TEXTURE_COORD_3): The generated 
control points are three floats that represent the s, t, and r texture coordi- 
nates. glTexCoord3 commands are generated internally when the map is 
evaluated. Note: The current texture coordinates are not changed as they 
would be if g1TexCoord were called directly. 

GL_MAP1_TEXTURE_COORD_4 (or GL_MAP2_TEXTURE_COORD_4): The generated 
control points are four floats that represent the s, t, r, and q texture coor- 
dinates. g1TexCoord4 commands are generated internally when the map 
is evaluated. Note: The current texture coordinates are not changed as 
they would be if g1TexCoord were called directly. 

Specifies the linear mapping of the parametric u parameter. 


Specifies the linear mapping of the parametric v parameter. This parame- 
ter is used only for 2D maps. 


Specifies the number of floats or doubles between control points in the 
*points data structure. The coordinates for each point occupy consecu- 
tive memory locations, but this parameter allows the points to be spaced 
as needed to let the data come from an arbitrary data structure. 


Specifies the number of control points in the u and v direction. 


A memory pointer that points to the control points. It can be a 2D or 3D 
array or any arbitrary data structure. 


None. 


glBegin, glColor, glEnable, glEvalCoord, glEvalMesh, glEvalPoint, 
glMapGrid, glNormal, glTexCoord, glVertex 


Defines a 1D or 2D mapping grid. 
<gl.h> 
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Variations: 


void glMapGridid(GLint un, GLdouble u7, GLdouble u2); 
void glMapGrid1f(GLint un, GLfloat u7, GLfloat u2); 
void glMapGrid2d(GLint un, GLdouble u7, GLdouble u2, 
GLint vn, GLdouble v7, GLdouble v2); 
void glMapGrid2f(GLint un, GLfloat u7, GLfloat u2, GLint vn, 
GLfloat v7, GLfloat v2); 


Description: This function establishes a 1D or 2D mapping grid. It is used with g1Map 
and glEvalMesh to efficiently evaluate a mapping and create a mesh of 


coordinates. 
Parameters: 
un, vn GLint: Specifies the number of grid subdivisions in the u or v direction. 
ul, u2 Specifies the lower and upper grid domain values in the u direction. 
v1, v2 Specifies the lower and upper grid domain values in the v direction. 
Returns: None. 
See Also: glEvalCoord, glEvalMesh, glEvalPoint, glMap1, glMap2 
gluBeginCurve 
Purpose: Begins a NURBS curve definition. 
Include File: <glu.h> 
Syntax: 


void gluBeginCurve(GLUnurbsObj *n0bj); 


Description: You use this function with gluEndCurve to delimit a NURBS curve defini- 
tion. 

Parameters: 

nObj GLUnurbsObj *: Specifies the NURBS object. 

Returns: None. 

See Also: gluEndCurve 

gluBeginSurface 

Purpose: Begins a NURBS surface definition. 


Include File: <glu.h> 
Syntax: 
void gluBeginSurface(GLUnurbsObj *n0bj); 


Reference 


Description: You use this function with gluEndSurface to delimit a NURBS surface 
definition. 

Parameters: 

nObj GLUnurbsObj *: Specifies the NURBS object. 

Returns: None. 

See Also: gluEndSurface 

gluBeginTrim 

Purpose: Begins a NURBS trimming loop definition. 


Include File: 
Syntax: 


<glu.h> 


void gluBeginTrim(GLUnurbsObj *n0bj); 


Description: 


Parameters: 
nObj 
Returns: 
See Also: 


gluCylinder 
Purpose: 
Include File: 
Syntax: 


You use this function with gluEndTrim to delimit a trimming curve defin- 
ition. A trimming curve is a curve or set of joined curves defined with 
gluNurbsCurve or gluPwlCurve. The gluBeginTrim and gluEndTrim func- 
tions must reside inside the gluBeginSurface/gluEndSurface delimiters. 
When you use trimming, the direction of the curve specifies which 
portions of the surface are trimmed. Surface area to the left of the travel- 
ing direction of the trimming curve is left untrimmed. Thus, clockwise- 
wound trimming curves eliminate the area inside them, and 
counterclockwise-wound trimming curves eliminate the area outside 
them. 


GLUnurbsObj *: Specifies the NURBS object. 
None. 
gluEndTrim 


Draws a quadric cylinder. 
<glu.h> 


void gluCylinder(GLUquadricObj *obj, GLdouble baseRadius, 


GLdouble topRadius, GLdouble height, 
GLint slices, GLint stacks); 
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Description: This function draws a hollow cylinder with no ends along the z-axis. If 
topRadius or bottomRadius is 0, a cone is drawn instead. The cylinder is 
projected height units along the positive z-axis. The slices argument 
controls the number of sides along the cylinder. The stacks argument 
controls the number of segments generated along the z-axis across the 


cylinder. 

Parameters: 

obj GLUquadricObj *: The quadric state information to use for rendering. 

baseRadius GLdouble: The radius of the base (z = 0) of the cylinder. 

topRadius GLdouble: The radius of the top (z = height) of the cylinder. 

height GLdouble: The height or length of the cylinder along the z-axis. 

slices GLint: The number of sides on the cylinder. 

stacks GLint: The number of segments in the cylinder along the z-axis. 

Returns: None. 

See Also: gluDeleteQuadric, gluNewQuadric, gluQuadricCallback, 
gluQuadricDrawStyle, gluQuadricNormals, gluQuadricOrientation, 
gluQuadricTexture 


gluDeleteNurbsRenderer 


Purpose: Destroys a NURBS object. 
Include File: <glu.h> 
Syntax: 


void gluDeleteNurbsRenderer(GLUnurbsObj *nobj); 


Description: This function deletes the NURBS object specified and frees any memory 
associated with it. 


Parameters: 

nObj GLUnurbsObj *: Specifies the NURBS object to delete. 
Returns: None. 

See Also: gluNewNurbsRenderer 

gluDeleteQuadric 

Purpose: Deletes a quadric state object. 


Include File: <glu.h> 
Syntax: 
void gluDeleteQuadric(GLUquadricObj *obj); 


Description: 


Reference 


This function deletes a quadric state object. After an object has been 
deleted, it cannot be used for drawing again. 


Parameters: 

obj GLUquadricObj *: The quadric state object to delete. 

Returns: None. 

See Also: gluNewQuadric, gluQuadricCallback, gluQuadricDrawStyle, 
gluQuadricNormals, gluQuadricOrientation, gluQuadricTexture 

gluDeleteTess 

Purpose: Deletes a tessellator object. 


Include File: 
Syntax: 


<glu.h> 


void gluDeleteTess(GLUtesselator *tobj); 


Description: 
Parameters: 
tobj 
Returns: 
See Also: 


gluDisk 


Purpose: 
Include File: 
Syntax: 


This function frees all memory associated with a tessellator object. 


GLUtesselator *: The tessellator object to delete. 
None. 
gluNewTess 


Draws a quadric disk. 
<glu.h> 


void gluDisk(GLUquadricObj *obj, GLdouble innerRadius, 


Description: 


Parameters: 
obj 
innerRadius 


outerRadius 


GLdouble outerRadius, GLint slices, GLint loops); 


This function draws a disk perpendicular to the z-axis. If innerRadius is 
O, a solid (filled) circle is drawn instead of a washer. The slices argument 
controls the number of sides on the disk. The loops argument controls 
the number of rings generated out from the z-axis. 


GLUquadricObj *: The quadric state information to use for rendering. 
GLdouble: The inside radius of the disk. 
GLdouble: The outside radius of the disk. 
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slices GLint: The number of sides on the cylinder. 

loops GLint: The number of rings out from the z-axis. 

Returns: None. 

See Also: gluDeleteQuadric, gluNewQuadric, gluQuadricCallback, 
gluQuadricDrawStyle, gluQuadricNormals, gluQuadricOrientation, 
gluQuadricTexture 

gluEndCurve 

Purpose: Ends a NURBS curve definition. 

Include File: <glu.h> 

Syntax: 


void gluEndCurve(GLUnurbsObj *nobj); 


Description: You use this function with gluBeginCurve to delimit a NURBS curve defi- 
nition. 

Parameters: 

nObj GLUnurbsObj *: Specifies the NURBS object. 

Returns: None. 

See Also: gluBeginCurve 

gluEndSurface 

Purpose: Ends a NURBS surface definition. 

Include File: <glu.h> 

Syntax: 


void gluEndSurface(GLUnurbsObj *n0bj); 


Description: You use this function with gluBeginSurface to delimit a NURBS surface 
definition. 

Parameters: 

nObj GLUnurbsObj *: Specifies the NURBS object. 

Returns: None. 


See Also: gluBeginSurface 


Reference 


gluEndTrim 

Purpose: Ends a NURBS trimming loop definition. 
Include File: <glu.h> 

Syntax: 


void gluEndTrim(GLUnurbsObj *n0bj) ; 


Description: You use this function with gluBeginTrim to mark the end of a NURBS 
trimming loop. See gluBeginTrim for more information on trimming 
loops. 

Parameters: 

nObj GLUnurbsObj *: Specifies the NURBS object. 

Returns: None. 

See Also: gluBeginTrim 

gluGetNurbsProperty 

Purpose: Retrieves a NURBS property. 

Include File: <gl.h> 

Syntax: 


void gluGetNurbsProperty(GLUnurbsObj *nObj, GLenum property, GLfloat *value); 


Description: This function retrieves the NURBS property specified for a particular 
NURBS object. See gluNurbsProperty for an explanation of the various 


properties. 

Parameters: 

nObj GLUnurbsObj *: Specifies the NURBS object. 

property GLenum *: The NURBS property to be retrieved. Valid properties are 
GLU_SAMPLING_TOLERANCE, GLU_DISPLAY_MODE, GLU_CULLING, 
GLU_AUTO_LOAD_MATRIX, GLU_PARAMETRIC_TOLERANCE, 
GLU_SAMPLING_METHOD, GLU_U_STEP, and GLU_V_STEP. See the 
gluNurbsProperty function for details on these properties. 

value GLfloat *: A pointer to the location into which the value of the named 
property is to be copied. 

Returns: None. 


See Also: gluNewNurbsRenderer, gluNurbsProperty 
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gluLoadSamplingMatrices 


Purpose: 
Include File: 
Syntax: 


Loads NURBS sampling and culling matrices. 
<gl.h> 


void gluLoadSamplingMatrices(GLUnurbsObj *nObj, const GLfloat modelMatrix[16], 


Description: 


const GLfloat projMatrix[16], 
const GLint viewport[4]); 


You use this function to recompute the sampling and culling matrices for 
a NURBS surface. The sampling matrix enables you to determine how 
finely the surface must be tessellated to satisfy the sampling tolerance. 
The culling matrix enables you to determine whether the surface should 
be culled before rendering. Usually, this function does not need to be 
called, unless the GLU_AUTO_LOAD_MATRIX property is turned off. This 
might be the case when using selection and feedback modes. 


Parameters: 

n0bj GLUnurbsObj *: Specifies the NURBS object. 
modelMatrix GLfloat[16]: Specifies the modelview matrix. 
projMatrix GLfloat[16]: Specifies the projection matrix. 
viewport GLint[4]: Specifies a viewport. 

Returns: None. 

See Also: gluNewNurbsRenderer, gluNurbsProperty 
gluNewNurbsRenderer 

Purpose: Creates a NURBS object. 

Include File: <glu.h> 

Syntax: 


GLUnurbsObj* gluNewNurbsRenderer (void) ; 


Description: 


Returns: 


See Also: 


This function creates a NURBS rendering object. This object is used to 
control the behavior and characteristics of NURBS curves and surfaces. 
The functions that allow the NURBS properties to be set all require this 
pointer. You must delete this object with gluDeleteNurbsRenderer when 
you are finished rendering your NURBS. 


A pointer to a new NURBS object. This object is used when you call the 
rendering and control functions. 


gluDeleteNurbsRenderer 


Reference 


gluNewQuadric 

Purpose: Creates a new quadric state object. 
Include File: <glu.h> 

Syntax: 


GLUquadricObj *gluNewQuadric(void) ; 


Description: This function creates a new opaque quadric state object to be used for 
drawing. The quadric state object contains specifications that determine 
how subsequent images will be drawn. 

Parameters: None. 

Returns: GLUquadricObj *: NULL if no memory is available; otherwise, a valid 
quadric state object pointer. 


See Also: gluDeleteQuadric, gluQuadricCallback, gluQuadricDrawStyle, 
gluQuadricNormals, gluQuadricOrientation, gluQuadricTexture 


gluNewTess 

Purpose: Creates a tessellator object. 
Include File: <glu.h> 

Syntax: 


GLUtriangulator0bj *gluNewTess(void) ; 


Description: This function creates a tessellator object. 
Parameters: None. 

Returns: GLUtriangulatorObj *: The new tessellator object. 
See Also: gluDeleteTess 

gluNurbsCallback 

Purpose: Defines a callback for a NURBS function. 


Include File: <glu.h> 
Syntax: 
void gluNurbsCallback(GLUnurbsObj *nObj, GLenum which, void(*fn)( )); 


Description: This function sets a NURBS callback function. The only supported call- 
back prior to GLU version 1.3 is G__ERROR. When an error occurs, this 
function is called with an argument of type GLenum. One of 37 NURBS 
errors can be specified by the constants GLU_NURBS_ERROR1 through 
GLU_NURBS_ERROR37. You can retrieve a character string definition of the 
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Parameters: 


nObj 
which 


fn 


Returns: 
See Also: 


Curves and Surfaces 


error with the function gluErrorString. These error codes are listed in 
Table 10.2. For GLU version 1.3 and later, GLU_ERROR has been superceded 
by GLU_NURBS_ERROR and a number of other callbacks listed under 
“Parameters.” 


GLUnurbsObj *: Specifies the NURBS object. 


GLenum: Specifies the callback being defined. Prior to GLU version 1.3, the 
only valid value was GLU_ERROR. For GLU version 1.3 and later (currently, 
only MacOS X) GLU_ERROR has been superceded by GLU_NURBS_ERROR 
and any of the following other callbacks: GLU_NURBS_BEGIN, 
GLU_NURBS_VERTEX, GLU_NURBS_NORMAL, GLU_NURBS_COLOR, 
GLU_NURBS_TEXTURE_COORD, GLU_NURBS_END, GLU_NURBS_BEGIN_DATA, 
GLU_NURBS_VERTEX_DATA, GLU_NURBS_NORMAL_DATA, GLU_NURBS_COLOR_DATA, 
GLU_NURBS_TEXTURE_COORD_DATA, and GLU_NURBS_END_DATA. 


void *(): Specifies the function that should be called for the callback. 
The following prototypes are used for the different callbacks: 


GLU_NURBS_BEGIN: void *(GLenum type) ; 

GLU_NURBS_BEGIN_DATA: void *(GLenum type, void *userData) 
GLU_NURBS_VERTEX: void *(GLfloat *vertex) ; 
GLU_NURBS_VERTEX_DATA: void (GLfloat *vertex, void *userData) 
GLU_NURBS_NORMAL: void *(GLfloat *normal) ; 
GLU_NURBS_NORMAL_DATA: void *(GLfloat *normal, void *userData) ; 
GLU_NURBS_COLOR: void *(GLfloat *color); 
GLU_NURBS_COLOR_DATA: void *(GLfloat *color, void *userData) ; 
GLU_NURBS_TEXTURE_COORD: void *(GLfloat *texCoord) ; 


GLU_NURBS_TEXTURE_COORD_DATA: void *(GLfloat *texCoord, void 
*userData) ; 


GLU_NURBS_END: void *(void); 
GLU_NURBS_END_DATA: void *(void userData) ; 
GLU_NURBS_ERROR: void *(GLenum error) ; 
None. 

gluErrorString 


Error Code 


GLU_NURBS_ERROR1 
GLU_NURBS_ERROR2 

GLU_NURBS_ ERRORS 

GLU_NURBS_ERROR4 

GLU_NURBS_ERRORS 

GLU_NURBS_ERROR6 

GLU_NURBS_ERROR7 

GLU_NURBS_ERROR8 

GLU_NURBS_ERROR9 

GLU_NURBS_ERROR10 
GLU_NURBS_ERROR11 
GLU_NURBS_ERROR12 
GLU_NURBS_ERROR13 
GLU_NURBS_ERROR14 
GLU_NURBS_ERROR15 
GLU_NURBS_ERROR16 
GLU_NURBS_ERROR17 
GLU_NURBS_ERROR18 
GLU_NURBS_ERROR19 
GLU_NURBS_ERROR20 
GLU_NURBS_ERROR21 
GLU_NURBS_ERROR22 
GLU_NURBS_ERROR23 
GLU_NURBS_ERROR24 
GLU_NURBS_ERROR25 
GLU_NURBS_ERROR26 
GLU_NURBS_ERROR27 
GLU_NURBS_ERROR28 
GLU_NURBS_ERROR29 
GLU_NURBS_ERROR3O 
GLU_NURBS_ERRORS1 
GLU_NURBS_ERROR32 
GLU_NURBS_ERROR3S 
GLU_NURBS_ERRORS4 
GLU_NURBS_ERROR35 
GLU_NURBS_ERROR36 
GLU_NURBS_ERROR37 


Reference 


TABLE 10.2 NURBS Error Codes 


Definition 


Spline order unsupported. 

Too few knots. 

Valid knot range is empty. 

Decreasing knot sequence knot. 

Knot multiplicity greater than order of spline. 
endcurve must follow bgncurve. 
bgncurve must precede endcurve. 
Missing or extra geometric data. 

Can’t draw pwlcurves. 

Missing or extra domain data. 

Missing or extra domain data. 

endtrim must precede endsurface. 
bgnsurface must precede endsurface. 
Curve of improper type passed as trim curve. 
bgnsurface must precede bgntrim. 
endtrim must follow bgntrim. 
bgntrim must precede endtrim. 
Invalid or missing trim curve. 

bgntrim must precede pwlcurve. 
pwicurve referenced twice. 

pwlcurve and nurbscurve mixed. 
Improper usage of trim data type. 
nurbscurve referenced twice. 
nurbscurve and pwlcurve mixed. 
nurbssurface referenced twice. 
Invalid property. 

endsurface must follow bgnsurface. 
Intersecting or misoriented trim curves. 
Intersecting trim curves. 

Unused. 

Unconnected trim curves. 

Unknown knot error. 

Negative vertex count encountered. 
Negative byte-stride encountered. 
Unknown type descriptor. 

Null control point reference. 

Duplicate point on pwlcurve. 
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gluNurbsCurve 

Purpose: Defines the shape of a NURBS curve. 
Include File: <glu.h> 

Syntax: 


void gluNurbsCurve(GLUnurbsObj *nObj, GLint nknots, GLfloat *knot, 
GLint stride, GLfloat *ctlArray, GLint order, GLenum type); 


Description: This function defines the shape of a NURBS curve. The definition of this 
curve must be delimited by gluBeginCurve and gluEndCurve. 


Parameters: 

nObj GLUnurbsObj *: A pointer to the NURBS object (created with 
gluNewNurbsRenderer). 

nknots GLint: The number of knots in *knots. This is the number of control 
points plus order. 

knot GLfloat *: An array of knot values in nondescending order. 

stride GLint: The offset, as a number of single-precision floating-point values, 
between control points. 

etlArray GLfloat *: A pointer to an array or data structure containing the control 
points for the NURBS surface. 

order GLint: The order of the NURBS surface. The order is 1 more than the 
degree. 

type GLenum: The type of surface. It can be any of the two-dimensional evalua- 
tor types: GL_MAP2_VERTEX_3, GL_MAP2_VERTEX_4, GL_MAP2_INDEX, 
GL_MAP2_COLOR_4, GL_MAP2_NORMAL, GL_MAP2_TEXTURE_COORD_1, 
GL_MAP2_TEXTURE_COORD_2, GL_MAP2_TEXTURE_COORD_3, and 
GL_MAP2_TEXTURE_COORD_4. 

Returns: None. 

See Also: gluBeginCurve, gluEndCurve, gluNurbsSurface 

gluNurbsProperty 

Purpose: Sets a NURBS property. 

Include File: <glu.h> 

Syntax: 


void gluNurbsProperty(GLUnurbsObj *nObj, GLenum property, GLfloat value) ; 


Description: This function sets the properties of the NURBS object. Valid properties are 
as follows: 


Reference 


GLU_SAMPLING_TOLERANCE: Sets the maximum length in pixels to use 
when using the GLU_PATH_LENGTH sampling method. The default is 50.0. 


GLU_DISPLAY_MODE: Defines how the NURBS surface is rendered. The 
value parameter can be GLU_FILL to use filled and shaded polygons, 
GLU_OUTLINE_POLYGON to draw just the outlines of the polygons (after 
tessellation), or GLU_LOUTLINE_PATCH to draw just the outlines of user- 
defined patches and trim curves. The default is GLU_FILL. 


GLU_CULLING: Interprets the value parameter as a Boolean value that indi- 
cates whether the NURBS curve should be discarded if its control points 
are outside the viewport. 


GLU_PARAMETRIC_TOLERANCE: Sets the maximum pixel distance used when 
the sampling method is set to GLU_PARAMETRIC_ERROR. The default is 0.5. 
This property was introduced in GLU version 1.1. 


GLU_SAMPLING_METHOD: Specifies how to tessellate the NURBS surface. This 
property was introduced in GLU version 1.1. The following values are 
valid: 


GLU_PATH_LENGTH specifies that surfaces rendered with the 
maximum pixel length of the edges of the tessellation polygons 
are not greater than the value specified by GLU_SAMPLING_ 
TOLERANCE. GLU_PARAMETRIC_ERROR specifies that the surface is 
rendered with the value of GLU_PARAMETRIC_TOLERANCE designat- 
ing the maximum distance, in pixels, between the tessellation 
polygons and the surfaces they approximate. 
GLU_DOMAIN_DISTANCE specifies, in parametric coordinates, how 
many sample points per unit length to take in the u and v 
dimensions. The default is GLU_PATH_LENGTH. 


GLU_U_STEP: Sets the number of sample points per unit length taken 
along the u dimension in parametric coordinates. This value is used when 
GLU_SAMPLING_METHOD is set to GLU_DOMAIN_DISTANCE. The default is 100. 
This property was introduced in GLU version 1.1. 


GLU_V_STEP: Sets the number of sample points per unit length taken 
along the v dimension in parametric coordinates. This value is used when 
GLU_SAMPLING_METHOD is set to GLU_DOMAIN_DISTANCE. The default is 100. 
This property was introduced in GLU version 1.1. 


GLU_AUTO_LOAD_MATRIX: Interprets the value parameter as a Boolean value. 
When it is set to GL_TRUE, it causes the NURBS code to download the 
projection matrix, the modelview matrix, and the viewport from the 
OpenGL server to compute sampling and culling matrices for each 
NURBS curve. Sampling and culling matrices are required to determine 
the tessellation of a NURBS surface into line segments or polygons and to 
cull a NURBS surface if it lies outside the viewport. If this mode is set to 
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GL_FALSE, the user needs to provide these matrices and a viewport for the 
NURBS renderer to use in constructing sampling and culling matrices. 
This can be done with the gluLoadSamplingMatrices function. The 
default value for this mode is GL_TRUE. Changing this mode does not 
affect the sampling and culling matrices until gluLoadSamplingMatrices 


is called. 

Parameters: 

nObj GLUnurbsObj *: The NURB object that is having a property modified. (It 
is created by calling glNewNurbsRenderer.) 

property GLenum: The property to be set or modified. It may be any of the follow- 
ing values: GLU_SAMPLING_TOLERANCE, GLU_DISPLAY_MODE, GLU_CULLING, 
GLU_AUTO_LOAD_MATRIX, GLU_PARAMETRIC_TOLERANCE, 
GLU_SAMPLING_METHOD, GLU_U_STEP, and GLU_V_STEP. 

value GLfloat: The value to which the indicated property is being set. 

Returns: None. 

See Also: gluGetNurbsProperty, gluGetString, gluLoadSamplingMatrices, 
gluNewNurbsRenderer, gluNewNurbsRenderer, gluNurbsCurve, 
gluPwlCurve 

gluNurbsSurface 

Purpose: Defines the shape of a NURBS surface. 

Include File: <glu.h> 

Syntax: 


void gluNurbsSurface(GLUnurbsObj *nObj, GLint uknotCount, GLfloat *uknot, 
GLint vknotCount, GLfloat *vknot, GLint uStride, 
GLint vStride, GLfloat *ctlArray, GLint uorder, 
GLint vorder, GLenum type) ; 


Description: This function defines the shape of a NURBS surface. It must be delimited 
by gluBeginSurface and gluEndSurface. The shape of the surface is 
defined before any trimming takes place. You can trim a NURBS surface 
by using gluBeginTrim/gluEndTrim and gluNurbsCurve or gluPwlCurve to 
do the trimming. 

Parameters: 


nObj GLUnurbsObj *: A pointer to the NURBS object. (It is created with 
gluNewNurbsRenderer.) 


uknotCount GLint: The number of knots in the parametric u direction. 


uknot 


vknotCount 
vknot 


uStride 


vStride 


ctlArray 


uorder 


vorder 


type 


Returns: 
See Also: 


Reference 


GLfloat *: An array of knot values that represent the knots in the u 
direction. These values must be nondescending. The length of the array is 
specified in uknotCount. 


GLint: The number of knots in the parametric v direction. 


GLfloat*: An array of knot values that represent the knots in the v direc- 
tion. These values must be nondescending. The length of the array is 
specified in vknotCount. 


GLint: The offset, as a number of single-precision, floating-point values, 
between successive control points in the parametric u direction in 
ctlArray. 


GLint: The offset, as a number of single-precision, floating-point values, 
between successive control points in the parametric v direction in 
ctlArray. 


GLfloat *: A pointer to an array containing the control points for the 
NURBS surface. The offsets between successive control points in the para- 
metric u and v directions are given by uStride and vStride. 


GLint: The order of the NURBS surface in the parametric u direction. The 
order is 1 more than the degree; hence, a surface that is cubic in u has a 
u order of 4. 


GLint: The order of the NURBS surface in the parametric v direction. The 
order is 1 more than the degree; hence, a surface that is cubic in v has a v 
order of 4. 


GLenum: The type of surface. It can be any of the 2D evaluator types: 
GL_MAP2_VERTEX_3, GL_MAP2_VERTEX_4, GL_MAP2_INDEX, GL_MAP2_COLOR_4, 
GL_MAP2_NORMAL, GL_MAP2_TEXTURE_COORD_1, GL_MAP2_TEXTURE_COORD_2, 
GL_MAP2_TEXTURE_COORD_3, and GL_MAP2_TEXTURE_COORD_4. 

None. 


gluBeginSurface, gluBeginTrim 


gluPartialDisk 


Purpose: 


Include File: 


Syntax: 


Draws a partial quadric disk. 
<glu.h> 


void gluPartialDisk(GLUquadricObj *obj, GLdouble innerRadius, 


GLdouble outerRadius, GLint slices, GLint loops, 
GLdouble startAngle, GLdouble sweepAngle) ; 
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Description: 


Parameters: 
obj 
innerRadius 
outerRadius 
slices 
loops 
startAngle 
sweepAngle 
Returns: 

See Also: 


gluPwiCurve 


Purpose: 
Include File: 
Syntax: 


This function draws a partial disk perpendicular to the z-axis. If 
innerRadius is O, a solid (filled) circle is drawn instead of a washer. The 
slices argument controls the number of sides on the disk. The loops 
argument controls the number of rings generated out from the z-axis. 
The startAngle argument specifies the starting angle of the disk with 0° 
at the top of the disk and 90° at the right of the disk. The sweepAngle 
argument specifies the portion of the disk in degrees. 


GLUquadricObj *: The quadric state information to use for rendering. 
GLdouble: The inside radius of the disk. 

GLdouble: The outside radius of the disk. 

GLint: The number of sides on the cylinder. 

GLint: The number of rings out from the z-axis. 

GLdouble: The start angle of the partial disk. 

GLdouble: The angular size of the partial disk. 

None. 


gluDeleteQuadric, gluNewQuadric, gluQuadricCallback, 
gluQuadricDrawStyle, gluQuadricNormals, gluQuadricOrientation, 
gluQuadricTexture 


Specifies a piecewise NURBS trimming curve. 
<glu.h> 


void gluPwlCurve(GLUnurbsObj *n0bj, GLint count, GLfloat *array, GLint stride, 


GLenum type); 


Description: 


This function defines a piecewise linear trimming curve for a NURBS 
surface. The array of points is in terms of the parametric u and v coordi- 
nate space. This space is a unit square exactly 1 unit in length along both 
axes. Clockwise-wound trimming curves eliminate the enclosed area; 
counterclockwise trimming curves discard the exterior area. Typically, a 
trimming region is first established around the entire surface area that 
trims away all points not on the surface. Then smaller trimming areas 
wound clockwise are placed within it to cut away sections of the curve. 
Trimming curves can be piecewise. This means one or more calls to 
gluPwlCurve or gluNurbsCurve can be called to define a trimming region 
as long as they share endpoints and define a close region in u/v space. 


Reference 


Parameters: 

nObj GLUnurbsObj *: Specifies the NURBS object being trimmed. 

count GLint: Specifies the number of points on the curve listed in *array. 

array GLfloat *: Specifies the array of boundary points for this curve. 

stride GLint: Specifies the offset between points on the curve. 

type GLenum: Specifies the type of curve. It can be GLU_MAP1_TRIM_2, used 
when the trimming curve is specified in terms of u and v coordinates, or 
GLU_MAP1_TRIM_3, used when a w (scaling) coordinate is also specified. 

Returns: None. 

gluQuadricCallback 

Purpose: Defines a quadric callback function. 

Include File: <glu.h> 

Syntax: 


void gluQuadricCallback(GLUquadricObj *obj, GLenum which, void (*fn)()); 


Description: This function defines callback functions to be used when drawing 
quadric shapes. At present, the only defined callback function is 
GLU_ERROR, which is called whenever an OpenGL or GLU error occurs. 


Parameters: 

obj GLUquadricObj *: The quadric state information to use for rendering. 

which GLenum: The callback function to define. It must be GLU_ERROR. 

fn void (*)(): The callback function (receives one GLenum containing the 
error). 

Returns: None 

See Also: gluDeleteQuadric, gluNewQuadric, gluQuadricDrawStyle, 
gluQuadricNormals, gluQuadricOrientation, gluQuadricTexture 

gluQuadricDrawStyle 

Purpose: Sets the drawing style of a quadric state object. 

Include File: <glu.h> 

Syntax: 


void gluQuadricDrawStyle(GLUquadricObj *obj, GLenum drawStyle) ; 


Description: This function selects a drawing style for all quadric shapes. 
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Parameters: 

obj GLUquadricObj *: The quadric state information to use for rendering. 

drawStyle GLenum: The drawing style. Valid styles are as follows: 
GLU_FILL: Quadrics are drawn filled, using polygon and strip primitives. 
GLU_LINE: Quadrics are drawn “wireframe,” using line primitives. 
GLU_SILHOUETTE: Quadrics are drawn using line primitives; only the 
outside edges are drawn. 
GLU_POINT: Quadrics are drawn using point primitives. 

Returns: None. 

See Also: gluDeleteQuadric, gluNewQuadric, gluQuadricCallback, 
gluQuadricNormals, gluQuadricOrientation, gluQuadricTexture 

gluQuadricNormals 

Purpose: Sets the type of lighting normals used for quadric objects. 


Include File: 
Syntax: 


<glu.h> 


void gluQuadricNormals(GLUquadricObj *obj, GLenum normals) ; 


Description: 


Parameters: 
obj 
normals 


Returns: 
See Also: 


This function sets the type of lighting normals that are generated when 
drawing shapes using the specified quadric state object. 


GLUquadricObj *: The quadric state information to use for rendering. 
GLenum: The type of normal to generate. Valid types are as follows: 
GLU_NONE: No lighting normals are generated. 


GLU_FLAT: Lighting normals are generated for each polygon to generate a 
faceted appearance. 


GLU_SMOOTH: Lighting normals are generated for each vertex to generate a 
smooth appearance. 


None. 


gluDeleteQuadric, gluNewQuadric, gluQuadricCallback, 
gluQuadricDrawStyle, gluQuadricOrientation, gluQuadricTexture 


gluQuadricOrientation 


Purpose: 
Include File: 


Sets the orientation of lighting normals for quadric objects. 
<glu.h> 
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Syntax: 
void gluQuadricOrientation(GLUquadricObj *obj, GLenum orientation) ; 


Description: This function sets the direction of lighting normals for hollow objects. 
The orientation parameter can be GLU_OUTSIDE to point lighting normals 
outward or GLU_INSIDE to point them inward. 


Parameters: 
obj GLUquadricObj *: The quadric state information to use for rendering. 


orientation GLenum: The orientation of lighting normals, GLU_OUTSIDE or GLU_INSIDE. 
The default is GLU_OUTSIDE. 


Returns: None. 


See Also: gluDeleteQuadric, gluNewQuadric, gluQuadricCallback, 
gluQuadricDrawStyle, gluQuadricNormals, gluQuadricTexture 


gluQuadricTexture 

Purpose: Enables or disables texture coordinate generation for texture-mapping 
images onto quadrics. 

Include File: <glu.h> 

Syntax: 


void gluQuadricTexture(GLUquadricObj *obj, GLboolean textureCoords) ; 


Description: This function controls whether texture coordinates are generated for 
quadric shapes. 
Parameters: 
obj GLUquadricObj *: The quadric state information to use for rendering. 
textureCoords GLboolean: GL_TRUE if texture coordinates should be generated; GL_FALSE 
otherwise. 
Returns: None. 
See Also: gluDeleteQuadric, gluNewQuadric, gluQuadricCallback, 
gluQuadricDrawStyle, gluQuadricNormals, gluQuadricOrientation 
gluSphere 
Purpose: Draws a quadric sphere. as 
Include File: <glu.h> @ 
Syntax: 


void gluSphere(GLUquadricObj *obj, GLdouble radius, GLint slices, GLint stacks) ; 
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Description: This function draws a hollow sphere centered at the origin. The slices 
argument controls the number of lines of longitude on the sphere. The 
stacks argument controls the number of lines of latitude on the sphere. 

Parameters: 

obj GLUquadricObj *: The quadric state information to use for rendering. 

radius GLdouble: The radius of the sphere. 

slices GLint: The number of lines of longitude on the sphere. 

stacks GLint: The number of lines of latitude on the sphere. 

Returns: None. 

See Also: gluDeleteQuadric, gluNewQuadric, gluQuadricCallback, 
gluQuadricDrawStyle, gluQuadricNormals, gluQuadricOrientation, 
gluQuadricTexture 

gluTessBeginContour 

Purpose: Specifies a new contour or hole in a complex polygon. 


Include File: 
Syntax: 


<glu.h> 


void gluTessBeginContour(GLUtesselator *tobj) ; 


Description: 


This function specifies a new contour or hole in a complex polygon. 


Parameters: 

tobj GLUtesselator *: The tessellator object to use for the polygon. 

Returns: None. 

See Also: gluTessBeginPolygon, gluTessEndPolygon, gluTessEndContour, 
gluTessVertex 

gluTessBeginPolygon 

Purpose: Starts tessellation of a complex polygon. 


Include File: 
Syntax: 


<glu.h> 


void gluTessBeginPolygon(GLUtesselator *tobj, GLvoid *data) ; 


Description: 
Parameters: 
tobj 
data 


This function starts tessellation of a complex polygon. 


GLUtesselator *: The tessellator object to use for the polygon. 
GLvoid *: The data that is passed to GLU_TESS_* DATA callbacks. 


Reference 


Returns: None. 

See Also: gluTessEndPolygon, gluTessBeginContour, gluTessEndContour, 
gluTessVertex 

gluTessCallback 

Purpose: Specifies a callback function for tessellation. 

Include File: <glu.h> 

Syntax: 


void gluTessCallback(GLUtesselator *tobj, GLenum which, void (*fn)()); 


Description: This function specifies a callback function for various tessellation func- 
tions. Callback functions do not replace or change the tessellator perfor- 
mance. Rather, they provide the means to add information to the 
tessellated output (such as color or texture coordinates). 


Parameters: 

tobj GLUtesselator *: The tessellator object to use for the polygon. 

which GLenum: The callback function to define. Valid functions appear in Table 
10.3 

fn void (*)(): The function to call. 

Returns: None. 


TABLE 10.3 Tessellator Callback Identifiers 
Constant Description 


GLU_TESS_BEGIN Specifies a function that is called to begin a GL_TRIANGLES, GL_ 
TRIANGLE_STRIP, or GL_TRIANGLE_FAN primitive. The function must 
accept a single GLenum parameter that specifies the primitive to be 
rendered and is usually set to g1Begin. 

GLU_TESS_BEGIN_DATA Like GLU_TESS_BEGIN, specifies a function [GLU 1.2] that is called to 
begin a GL_TRIANGLES, GL_TRIANGLE_STRIP, or GL_TRIANGLE_FAN prim- 
itive. The function must accept a Glenum parameter that specifies the 
primitive to be rendered and a GLvoid pointer from the call to 


gluTessBeginPolygon. 
GLU_TESS_COMBINE Specifies a function that is called when [GLU 1.2] vertices in the 
polygon are coincident; that is, they are equal. 
GLU_TESS_COMBINE_DATA Like GLU_TESS_COMBINE, specifies a function [GLU 1.2] that is called 


when vertices in the polygon are coincident. The function also receives 
a pointer to the user data from gluTessBeginPolygon. 


543 


OL 


544 


CHAPTER 10 Curves and Surfaces 


TABLE 10.3 Continued 

Constant Description 

GLU_TESS_EDGE_FLAG Specifies a function that marks whether succeeding GLU_TESS_VERTEX 
callbacks refer to original or generated vertices. The function must 
accept a single GLboolean argument that is GL_TRUE for original and 
GL_FALSE for generated vertices. 

GLU_TESS_EDGE_FLAG_DATA Specifies a function similar to the GLU_TESS_EDGE_FLAG, with the excep- 
tion that a void pointer to user data is also accepted. 


GLU_TESS_END Specifies a function that marks the end of a drawing primitive, usually 
glEnd. It takes no arguments. 

GLU_TESS_END_DATA Specifies a function similar to GLU_TESS_END, with the addition of a void 
pointer to user data. 

GLU_TESS_ERROR Specifies a function that is called when an error occurs. It must take a 
single argument of type GLenum. 

GLU_TESS_VERTEX Specifies a function that is called before every vertex is sent, usually 


with glVertex3dv. The function receives a copy of the third argument 
to gluTessVertex. 

GLU_TESS_VERTEX_DATA Like GLU_TESS_VERTEX, specifies a function [GLU 1.2] that is called 
before every vertex is sent. The function also receives a copy of the 
second argument to gluTessBeginPolygon. 


gluTessEndContour 

Purpose: Ends a contour in a complex polygon. 
Include File: <glu.h> 

Syntax: 


void gluTessEndContour(GLUtesselator *tobj); 


Description: This function ends the current polygon contour. 

Parameters: 

tobj GLUtesselator *: The tessellator object to use for the polygon. 

Returns: None. 

See Also: gluTessBeginPolygon, gluTessBeginContour, gluTessEndPolygon, 
gluTessVertex 

gluTessEndPolygon 

Purpose: Ends tessellation of a complex polygon and renders it. 


Include File: <glu.h> 
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Syntax: 
void gluTessEndPolygon(GLUtesselator *tobj); 


Description: This function ends tessellation of a complex polygon and renders the 
final result. 

Parameters: 

tobj GLUtesselator *: The tessellator object to use for the polygon. 

Returns: None. 

See Also: gluTessBeginPolygon, gluTessBeginContour, gluTessEndContour, 
gluTessVertex 

gluTessProperty 

Purpose: Sets a tessellator property value. 


Include File: <glu.h> 
Syntax: 
void gluTessProperty(GLUtesselator *tobj, GLenum which, GLdouble value); 


Description: This function sets a tessellator property value. 

Parameters: 

tobj GLUtesselator *: The tessellator object to change. 

which GLenum: The property to change: GLU_TESS_BOUNDARY_ONLY, 
GLU_TESS_TOLERANCE, or GLU_TESS_WINDING_RULE. 

value GLdouble: The value for the property. 


For GLU_TESS_BOUNDARY_ONLY, the value can be GL_TRUE or GL_FALSE. If 
GL_TRUE, only the boundary of the polygon is displayed (no holes). 

For GLU_TESS_TOLERANCE, the value is the coordinate tolerance for vertices 
in the polygon. 

For GLU_TESS_WINDING_RULE, the value is one of 
GLU_TESS_WINDING_NONZERO, GLU_TESS_WINDING_ POSITIVE, 
GLU_TESS_WINDING_NEGATIVE, GLU_TESS_WINDING_ABS_GEQ_TWO, or 
GLU_TESS_WINDING_ODD. 


Returns: None. 


See Also: gluTessBeginPolygon, gluTessEndPolygon, gluTessBeginContour, 
gluTessEndContour, gluTessCallback, gluTessVertex, gluNewTess, 
gluDeleteTess 
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gluTessVertex 

Purpose: Adds a vertex to the current polygon path. 
Include File: <glu.h> 

Syntax: 


void gluTessVertex(GLUtesselator *tobj, GLdouble v[3], void *data); 


Description: This function adds a vertex to the current tessellator path. The data argu- 
ment is passed through to the GL_VERTEX callback function. 


Parameters: 

tobj GLUtesselator *: The tessellator object to use for the polygon. 

Vv GLdouble[3]: The 3D vertex. 

data void *: A data pointer to be passed to the GL_VERTEX callback function. 
Returns: None. 

See Also: gluTessBeginPolygon, gluTessEndPolygon, gluTessBeginContour, 


gluTessEndContour 


CHAPTER 11 


It’s All About the Pipeline: Faster 
Geometry Throughput 


by Richard S. Wright, Jr. 


WHAT YOU’LL LEARN IN THIS CHAPTER: 


How To 


Assemble polygons to create 3D objects 
Optimize object display with display lists 
Store and transfer geometry more efficiently 


Reduce geometric bandwidth 


Functions You'll Use 


glBegin/glEnd/glVertex 
glNewList/glEndList/glCallList 
glEnableClientState/ 
glDisableClientState/ 
glVertexPointer/glNormalPointer/ 
glTexCoordPointer/glColorPointer/ 
glEdgeFlagPointer/ 
glFogCoordPointer/ 
glSecondaryColorPointer/ 
glArrayElement/glDrawArrays/ 
gliInterleavedArrays 
glDrawElements/ 
glDrawRangeElements/ 
glMultiDrawElements 


In the preceding chapters, we covered the basic OpenGL rendering techniques and tech- 
nologies. Using this knowledge, there are few 3D scenes you can envision that cannot be 
realized using only the first half of this book. Now, however, we turn our attention to the 
techniques and practice of rendering complex geometric models using your newfound 
knowledge of OpenGL rendering capabilities. 


We begin with a basic overview of the many complex models assembled from simpler 
pieces. We then progress to some new OpenGL functionality that helps you more quickly 
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move geometry and other OpenGL commands to the hardware renderer (graphics card). 
Finally, we introduce you to some higher level ideas to eliminate costly drawing 
commands and geometry that is outside your field of view. 


Model Assembly 101 


Generally speaking, all 3D objects rendered with OpenGL are composed of some number 
of the 10 basic OpenGL rendering primitives: GL_POINTS, GL_LINES, GL_LINE_STRIP, 
GL_LINE_LOOP, GL_TRIANGLES, GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN, GL_QUADS, 
GL_QUAD_STRIPS, or GL_POLYGON. Managing all the individual vertices and primitive groups 
can become quite complex when the geometry grows in size or complexity. The usual way 
of dealing with highly complex objects is simply “divide and conquer”—break it down 
into many smaller, simpler pieces. 


For example, the SNOWMAN sample in Chapter 10, “Curves and Surfaces,” was simply 
made out of spheres, cylinders, cones, and disks cleverly arranged with a few geometric 
transformations. We begin this chapter with another simple model that is composed of 
more than one individual part: a model of a metallic bolt (such as those holding your disk 
drive together). Although this particular bolt might not exist in any hardware store, it 
does have the essential features of our end goal. 

The bolt will have a six-sided head and a threaded shaft, as do many typical steel bolts. 
Because this is a learning exercise, we simplify the threads by making them raised on the 
surface of the bolt shaft rather than carved out of the shaft. Figure 11.1 provides a rough 
sketch of what we’re aiming for. We build the three major components of this bolt—the 
head, shaft, and threads—individually and then put them together to form the final 
object. 


Head 


Shaft 


Threads 


FIGURE 11.1. The hex bolt to be modeled in this chapter. 


Pieces and Parts 

Any given programming task can be separated into smaller, more manageable tasks. 
Breaking down the tasks makes the smaller pieces easier to handle and code, and intro- 
duces some reusability into the code base as well. Three-dimensional modeling is no 
exception; you will typically create large, complex systems out of many smaller and more 
manageable pieces. 


Model Assembly 101 


As previously mentioned, we have decided to break down the bolt into three pieces: head, 
shaft, and thread. Certainly, breaking down the tasks makes it much simpler for us to 
consider each section graphically, but it also gives us three objects that we can reuse. In 
more complex modeling applications, this reusability is of crucial importance. In a CAD- 
type application, for example, you would probably have many different bolts to model 
with various lengths, thicknesses, and thread densities. Instead of, say, a RenderHead func- 
tion that draws the head of the bolt, you might want to write a function that takes para- 
meters specifying the number of sides, thickness, and diameter of the bolt head. 


Another thing we do is model each piece of our bolt in coordinates that are most conve- 
nient for describing the object. Most often, individual objects or meshes are modeled 
around the origin and then translated and rotated into place. Later, when composing the 
final object, we can translate the components, rotate them, and even scale them if neces- 
sary to assemble our composite object. We do this for two very good reasons. First, this 
approach enables rotations to take place around the object’s geometric center instead of 
some arbitrary point off to one side (depending on the whim of the modeler). The second 
reason will become more obvious later in the chapter. For now, suffice it to say that it is 
very useful to know the distance from any given point to the center of an object and to be 
able to more easily calculate an object’s 3D extents (how big it is). 


The Head 

The head of our bolt has six smooth sides and is smooth on top and bottom. We can 
construct this solid object with two hexagons that represent the top and bottom of the 
head and a series of quadrilaterals around the edges to represent the sides. We could use 
GL_QUAD_STRIP to draw the head with a minimum number of vertices; however, as we 
discussed previously in Chapter 6, “More on Colors and Materials,” this approach would 
require that each edge share a surface normal. By using individual quads (GL_QUADS), we 
can at least cut down on sending one additional vertex to OpenGL per side (as opposed to 
sending down two triangles). For a small model such as this, the difference is negligible. 
For larger models, this step could mean a significant savings. 


Figure 11.2 illustrates how the bolt head is constructed with the triangle fan and quads. 
We use a triangle fan with six triangles for the top and bottom sections of the head. Then 
we compose each face of the side of the bolt with a single quad. 


We used a total of 18 primitives to draw the bolt head: 6 triangles (or one fan) each on the 
top and bottom and 6 quads to compose the sides of the bolt head. Listing 11.1 contains 
the function that renders the bolt head. Figure 11.3 shows what the bolt head looks like 
when rendered by itself (the completed program is the BOLT sample on the CD). This 
code contains only functions we've already covered, but it’s more substantial than any of 
the simpler chapter examples. Also, note that the origin of the coordinate system is in the 
exact center of the bolt head. 
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FIGURE 11.2 Primitive outline of bolt head. 


FIGURE 11.3. Output from the head program. 


LISTING 11.1 Code to Render the Bolt Head 


TUTTTTT TTT TTT TTT TTT TT TTL TL 
// Creates the head of the bolt 
void RenderHead (void) 


{ 

float x,y,angle; // Calculated positions 

float height = 25.0f; // Thickness of the head 

float diameter = 30:0f; // Diameter of the head 

GLTVector3 vNormal,vCorners[4]; // Storage of vertices and normals 


float step = (3.1415f/3.0f); // step = 1/6th of a circle = hexagon 
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LISTING 11.1 Continued 


// Set material color for head of bolt 
glColor3f(@.0f, 0.0f, @.7f); 


// Begin a new triangle fan to cover the top 
glFrontFace(GL_CCW) ; 
g1Begin(GL_TRIANGLE_FAN) ; 


// All the normals for the top of the bolt point straight up 
// the z axis. 
glNormal3f(0.0f, @.0f, 1.0f); 


// Center of fan is at the origin 
glVertex3f(0.0f, 0.0f, height/2.0f); 


// Divide the circle up into 6 sections and start dropping 

// points to specify the fan. We appear to be winding this 

// fan backwards. This has the effect of reversing the winding 

// of what would have been a CW wound primitive. Avoiding a state 
// change with glFrontFace(). 


// First and Last vertex closes the fan 
glVertex3f(0.0f, diameter, height/2.0f); 


for(angle = (2.0f*3.1415f)-step; angle >= 0; angle -= step) 
{ 
// Calculate x and y position of the next vertex 
x = diameter*(float)sin(angle) ; 
y = diameter*(float)cos(angle) ; 


// Specify the next vertex for the triangle fan 
glVertex3f(x, y, height/2.0f) ; 
} 


// Last vertex closes the fan 
glVertex3f(@.@f, diameter, height/2.0f); 


// Done drawing the fan that covers the bottom 
glEnd(); 


// Begin a new triangle fan to cover the bottom 
glBegin(GL_TRIANGLE_FAN); 
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LISTING 11.1 Continued 


// Normal for bottom points straight down the negative z axis 
glNormal3f(0.0f, @.0f, -1.0f); 


// Center of fan is at the origin 
glVertex3f(0.0f, 0.0f, -height/2.0f); 


// Divide the circle up into 6 sections and start dropping 
// points to specify the fan 
for(angle = @.0f; angle < (2.0f*3.1415f); angle += step) 

{ 

// Calculate x and y position of the next vertex 

x = diameter*(float)sin(angle) ; 

y = diameter* (float) cos(angle) ; 


// Specify the next vertex for the triangle fan 
glVertex3f(x, y, -height/2.0f); 
} 


// Last vertex, used to close the fan 
glVertex3f(0.0f, diameter, -height/2.0f); 


// Done drawing the fan that covers the bottom 
glEnd(); 


// Build the sides out of triangles (two each). Each face 
// will consist of two triangles arranged to form a 

// quadrilateral 

g1Begin(GL_QUADS) ; 


// Go around and draw the sides 

for(angle = 0.0f; angle < (2.0f*3.1415f); angle += step) 
{ 
// Calculate x and y position of the next hex point 
x = diameter* (float)sin(angle) ; 
y = diameter*(float)cos(angle) ; 


// start at bottom of head 


vCorners[@][@] = x; 
vCorners[®][1] = y; 
vCorners[@][2] = -height/2.0f; 
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LISTING 11.1 Continued 


// extrude to top of head 
vCorners[1][] x 
vCorners[1][1] y; 
vCorners[1] [2] height/2.0f; 


" 


// Calculate the next hex point 
xX = diameter*(float)sin(angle+step) ; 
y = diameter*(float)cos(angletstep) ; 


// Make sure we aren't done before proceeding 
if(anglet+step < 3.1415*2.0) 

{ 

// If we are done, just close the fan at a 

// known coordinate. 

vCorners[2][] = x; 

vCorners[2][1] = y; 

vCorners[2][2] = height/2.0f; 


vCorners[3][@] = x; 
vCorners[3][1] = y; 
vCorners[3][2] = -height/2.0f; 


else 


// We aren't done, the points at the top and bottom 
// of the head. 

vCorners[2][0] = 0.Of; 

vCorners[2][1] = diameter; 

vCorners[2][2] = height/2.0f; 


vCorners[3] [0] 
vCorners[3][1] 
vCorners[3] [2] 
} 


0.0f; 
diameter; 
-height/2.0f; 


// The normal vectors for the entire face will 

// all point the same direction 

gltGetNormalVector(vCorners[®], vCorners[1], vCorners[2], vNormal); 
glNormal3fv(vNormal) ; 


// Specify each quad separately to lie next 
// to each other. 
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LISTING 11.1 Continued 


glVertex3fv(vCorners[Q]); 
glVertex3fv(vCorners[1]); 
glVertex3fv(vCorners[2]); 
glVertex3fv(vCorners[3]); 
} 


glEnd(); 
} 


The Shaft 


The shaft of the bolt is nothing more than a cylinder with a bottom on it. We compose a 
cylinder by plotting x,z values around in a circle and then take two y values at these 
points and get polygons that approximate the wall of a cylinder. This time, however, we 
compose this wall entirely out of a quad strip because each adjacent quad can share a 
normal for smooth shading (see Chapter 5, “Color, Materials, and Lighting: The Basics”). 
Figure 11.4 shows the rendered cylinder. 


FIGURE 11.4 The shaft of the bolt, rendered as a quad strip around the shaft body. 


Model Assembly 101 


We also create the bottom of the shaft with a triangle fan, as we did for the bottom of the 
bolt head previously. Notice now, however, that the smaller step size around the circle 
yields smaller flat facets, which make the cylinder wall more closely approximate a 
smooth curve. The step size also matches that used for the shaft wall so that they match 
evenly. 


Listing 11.2 provides the code to produce this cylinder. Notice that the normals are not 
calculated for the quads using the vertices of the quads. We usually set the normal to be 
the same for all vertices, but here, we break with this tradition to specify a new normal for 
each vertex. Because we are simulating a curved surface, the normal specified for each 
vertex is normal to the actual curve. (If this description seems confusing, review Chapter 5 
on normals and lighting effects.) 


LISTING 11.2 Code to Render the Shaft of the Bolt 


FETTTTTTTTLLT TTT TATA TTA TL 
// Creates the shaft of the bolt as a cylinder with one end 


// closed. 

void RenderShaft (void) 
{ 
float x,z,angle; // Used to calculate cylinder wall 
float height = 75.0f; // Height of the cylinder 
float diameter = 20.0f; // Diameter of the cylinder 
GLTVector3 vNormal,vCorners[2]; // Storage for vertex calculations 
float step = (3.1415f/50.0f); // Approximate the cylinder wall with 


// 100 flat segments. 


// Set material color for head of screw 
glColor3f(0.0f, 0.0f, 0.7f); 


// First assemble the wall as 100 quadrilaterals formed by 
// placing adjoining Quads together 

glFrontFace(GL_CCW) ; 

glBegin(GL_QUAD_STRIP) ; 


// Go around and draw the sides 
for(angle = (2.0f*3.1415f); angle > @.@f; angle -= step) 
{ 
// Calculate x and y position of the first vertex 
x = diameter*(float)sin(angle) ; 
z = diameter*(float)cos(angle) ; 


// Get the coordinate for this point and extrude the 
// length of the cylinder. 


555 


LL 


556 CHAPTER 11 It’s All About the Pipeline: Faster Geometry Throughput 


LISTING 11.2 Continued 


vCorners[0][0] = x; 
vCorners[@][1] = -height/2.0f; 
vCorners[0][2] = z; 


vCorners[1][®] = x; 
vCorners[1][1] = height/2.0f; 
vCorners[1][2] = z; 


// Instead of using real normal to actual flat section 

// Use what the normal would be if the surface was really 

// curved. Since the cylinder goes up the Y axis, the normal 

// points from the Y axis out directly through each vertex. 

// Therefore we can use the vertex as the normal, as long as 

// we reduce it to unit length first and assume the y component 
// to be zero 

vNormal[0] = vCorners[1][0]; 

vNormal[1] Q.0f; 

vNormal[2] = vCorners[1][2]; 


// Reduce to length of one and specify for this point 
gltNormalizeVector(vNormal) ; 

glNormal3fv(vNormal) ; 

glVertex3fv(vCorners[Q]); 

glVertex3fv(vCorners[1]); 

} 


// Make sure there are no gaps by extending last quad to 

// the original location 

glVertex3f (diameter* (float)sin(2.0f*3.1415f), -height/2.0f, 
diameter* (float)cos(2.0f*3.1415f) ); 


glVertex3f (diameter*(float)sin(2.0f*3.1415f), height/2.0f, 
diameter* (float)cos(2.0f*3.1415f)); 


glEnd(); // Done with cylinder sides 


// Begin a new triangle fan to cover the bottom 
g1Begin(GL_TRIANGLE_FAN) ; 
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LISTING 11.2 Continued 


// Normal points down the Y axis 
glNormal3f(0.0f, -1.0f, 0.0f); 


// Center of fan is at the origin 
glVertex3f(0.0f, -height/2.0f, 0.0f); 


// Spin around matching step size of cylinder wall 
for(angle = (2.0f*3.1415f); angle > @.0f; angle -= step) 
{ 
// Calculate x and y position of the next vertex 
x = diameter*(float)sin(angle) ; 
z = diameter*(float)cos(angle); 


// Specify the next vertex for the triangle fan 
glVertex3f(x, -height/2.0f, z); 
} 


// Be sure loop is closed by specifying initial vertex 
// on arc as the last too 
glVertex3f (diameter*(float)sin(2.0f*3.1415f), -height/2.0f, 
: diameter* (float)cos(2.0f*3.1415f)); 
glEnd(); 
} 


The Thread 

The thread is the most complex part of the bolt. It’s composed of two planes arranged in a 
V shape that follows a corkscrew pattern up the length of the shaft. Figure 11.5 shows the 
rendered thread, and Listing 11.3 provides the OpenGL code used to produce this shape. 
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FIGURE 11.5 The bolt threads winding up the shaft (shown without shaft). 


LISTING 11.3 Code to Render the Threads 


LULU LTT TALL A TT 
// Spiraling thread 
void RenderThread(void) 


{ 

float x,y,z,angle; // Calculate coordinates and step angle 
float height = 75.0f; // Height of the threading 

float diameter = 20.0f; // Diameter of the threading 
GLTVector3 vNormal, vCorners[4]; // Storage for normal and corners 

float step = (3.1415f/32.0f); // one revolution 

float revolutions = 7.0f; // How many times around the shaft 
float threadWidth = 2.0f; // How wide is the thread 

float threadThick = 3.0f; // How thick is the thread 

float zstep = .125f; // How much does the thread move up 


// the Z axis each time a new segment 
// is drawn. 
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LISTING 11.3 Continued 


// Set material color for head of screw 
glColor3f(0.0f, 0.0f, 0.4f); 


z = -height/2.0f+2.0f; // Starting spot almost to the end 


// Go around and draw the sides until finished spinning up 
for(angle = 0.0f; angle < GLT_PI * 2.0f *revolutions; angle += step) 
{ 
// Calculate x and y position of the next vertex 
x = diameter*(float)sin(angle) ; 
y = diameter*(float)cos(angle) ; 


// Store the next vertex next to the shaft 
vCorners[@][0] = x; 
vCorners[0][1] = y; 
vCorners[0][2] = 


i) 
N 


// Calculate the position away from the shaft 
x = (diameter+threadWidth) *(float)sin(angle) ; 
y = (diameter+threadWidth) * (float) cos(angle) ; 


vCorners[1][®] = x; 
vCorners[1][1] = y; 
vCorners[1][2] 


" 
N 


// Calculate the next position away from the shaft 
x = (diameter+threadWidth) *(float)sin(angletstep) ; 
y = (diameter+threadWidth) *(float)cos(angle+step) ; 


vCorners[2][0] = x; 
vCorners[2][1] = y; 
vCorners[2][2] = z + zstep; 


// Calculate the next position along the shaft 
x = (diameter) *(float)sin(angletstep) ; 
y = (diameter) *(float)cos(angle+step) ; 


vCorners[3][0] = x; 
vCorners[3][1] = y; 
vCorners[3][2] = z+ zstep; 
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LISTING 11.3 Continued 


// We'll be using triangles, so make 

// counterclockwise polygons face out 

glFrontFace(GL_CCW) ; 

glBegin(GL_TRIANGLES); // Start the top section of thread 


// Calculate the normal for this segment 
gltGetNormalVector(vCorners[®], vCorners[1], vCorners[2], vNormal) ; 
glNormal3fv(vNormal) ; 


// Draw two triangles to cover area 
glVertex3fv(vCorners[Q]); 
glVertex3fv(vCorners[1]); 
glVertex3fv(vCorners[2]) ; 


glVertex3fv(vCorners[2]) ; 
glVertex3fv(vCorners[3]); 
glVertex3fv(vCorners[Q]); 


glEnd() ; 


// 
// 


Move the edge along the shaft slightly up the z axis 
to represent the bottom of the thread 


vCorners[®][2] += threadThick; 
vCorners[3][2] += threadThick; 


// 
// 


Recalculate the normal since points have changed, this 
time it points in the opposite direction, so reverse it 


gltGetNormalVector(vCorners[®], vCorners[1], vCorners[2], vNormal) ; 
vNormal[@] = -vNormal[Q]; 


vNormal[1] 
vNormal[2] 


// 
// 


" 


-vNormal[1]; 
-vNormal[2]; 


Switch to clockwise facing out for underside of the 
thread. 


glFrontFace(GL_CW) ; 


// 


Draw the two triangles 


glBegin(GL_TRIANGLES) ; 


glNormal3fv(vNormal) ; 


glVertex3fv(vCorners[Q]); 
glVertex3fv(vCorners[1]); 
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LISTING 11 3 Continued 


glVertex3fv(vCorners[2]); 


glVertex3fv(vCorners[2]); 

glVertex3fv(vCorners[3]); 

glVertex3fv(vCorners[Q]); 
glEnd(); 


// Creep up the Z axis 
z += zstep; 


} 


Putting It Together 

We assemble the bolt by drawing all three sections in their appropriate location. All 
sections are translated and rotated appropriately into place. The shaft is not modified at 
all, and the threads must be rotated to match the shaft. Finally, the head of the bolt must 
be rotated and translated to put it in its proper place. Listing 11.4 provides the rendering 
code that manipulates and renders the three bolt components. Figure 11.6 shows the final 
output of the bolt program. 


FIGURE 11.6 Output from the bolt program. 
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LISTING 11.4 Code to Render All the Pieces in Place 


// Called to draw scene 

void RenderScene(void) 
{ 
// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


// Save the matrix state 
glMatrixMode (GL_MODELVIEW) ; 
glPushMatrix(); 


// Rotate about x and y axes 
glRotatef(xRot, 1.0f, @.0f, 0.0f); 
glRotatef(yRot, 0.0f, @.0f, 1.0f); 


// Render just the Thread of the nut 
RenderShaft() ; 


glPushMatrix(); 
glRotatef(-90.0f, 1.0f, 0.0f, 0.0f); 
RenderThread(); 


glTranslatef (0.0f ,0.0f,45.0f) ; 
RenderHead() ; 
glPopMatrix() ; 


glPopMatrix(); 


// Swap buffers 
glutSwapBuffers(); 
} 


So why all the gymnastics to place all these pieces together? We easily could have adjusted 
our geometry so that all the pieces would be drawn in their correct location. The point 
shown here is that many pieces modeled about their own local origins can be arranged 
together in a scene quite easily to create a more sophisticated model or environment. This 
basic principle and technique form the foundation of creating your own scene graph (see 
Chapter 1, “Introduction to 3D Graphics and OpenGL”) or virtual environment. We have 
been putting this principle into practice all along with the SPHEREWORLD samples in 
each chapter. In a complex and persistent (saved to disk) 3D environment, each piece’s 
position and orientation could be stored individually using a GLTFrame structure from the 
glTools library. 
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Display Lists 

The BOLT program produces a reasonable representation of the metal bolt we set out to 
model. Consisting of more than 1,700 triangles, this bolt is the most complex manually 
generated example in this book so far in terms of geometry. Comparatively speaking, 
however, this number of triangles isn’t anywhere close to the largest number of polygons 
you'll encounter when composing larger scenes and more complex objects. In fact, the 
latest 3D accelerated graphics cards are rated at millions of triangles per second, and that’s 
for the cheap ones! One of the goals of this chapter is to introduce you to some more effi- 
cient ways to store and render your geometry. One of the simplest and most effective ways 
to do this is to use OpenGL display lists. 


OPTIMIZING MODEL RENDERING 

In our BOLT example, we constructed the model by applying mathematics to represent the 
curves and surfaces as equations. Using points along these equations, we constructed a series of 
triangles to create the representative shape. Although the bolt head and shaft were simple, the 
code to create the thread geometry can be a bit more intimidating. In general, creating models 
or geometry can be quite time consuming due to many factors. Perhaps you have to compute all 
the vertices and normals such as we have here. Perhaps you need to read these values from disk 
or retrieve them over a network. With these considerations in mind, rendering performance could 
be hampered more by other tasks related to creating the geometry than by the actual rendering 
itself. OpenGL provides two solutions to overcoming these issues, each of which has its own 
merits. These solutions, display lists and vertex arrays, are the main focus of the remainder of this 
chapter. 


Batch Processing 

OpenGL has been described as a software interface to graphics hardware. As such, you 
might imagine that OpenGL commands are somehow converted into some specific hard- 
ware commands or operators by the driver and then sent on to the graphics card for 
immediate execution. If so, you would be mostly correct. Most OpenGL rendering 
commands are, in fact, converted into some hardware-specific commands, but these 
commands are not dispatched immediately to the hardware. Instead, they are accumulated 
in a local buffer until some threshold is reached, at which point they are flushed to the 
hardware. 


The primary reason for this type of arrangement is that trips to the graphics hardware take 
a long time, at least in terms of computer time. To a human being, this process might take 
place very quickly, but to a CPU running at many billions of cycles per second, this is like 
waiting for a cruise ship to sail from North America to Europe and back. You certainly 
would not put a single person on a ship and wait for the ship to return before loading up 
the next person. If you have many people to send to Europe, you are going to cram as 
many people on the ship as you can! This analogy is very accurate: It is faster to send a 
large amount of data (within some limits) over the system bus to hardware all at once 
than to break it down into many bursts of smaller packages. 
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Keeping to the analogy, you also do not have to wait for the first cruise ship to return 
before you can begin filling the next ship with passengers. Sending the buffer to the 
graphics hardware (a process called flushing) is an asynchronous operation. This means that 
the CPU can move on to other tasks and does not have to wait for the batch of rendering 
commands just sent to be completed. You can literally have the hardware rendering a 
given set of commands while the CPU is busy calling a new set of commands for the next 
graphics image (typically called a frame when you’re creating an animation). This type of 
parallelization between the graphics hardware and the host CPU is highly efficient and 
often sought after by performance-conscious programmers. 


Three events trigger a flush of the current batch of rendering commands. The first occurs 
when the driver’s command buffer is full. You do not have access to this buffer, nor do 
you have any control over the size of the buffer. The hardware vendors work hard to tune 
the size and other characteristics of this buffer to work well with their devices. A flush also 
occurs when you execute a buffer swap. The buffer swap cannot occur until all pending 
commands have been executed (you want to see what you have drawn!), so the flush is 
initiated, followed by the command to perform the buffer swap. A buffer swap is an 
obvious indicator to the driver that you are done with a given scene and that all 
commands should be rendered. However, if you are doing single-buffered rendering, 
OpenGL has no real way of knowing when you’re done sending commands and thus 
when to send the batch of commands to the hardware for execution. To facilitate this 
process, you can call the following function to manually trigger a flush: 


void glFlush(void) ; 


Some OpenGL commands, however, are not buffered for later execution—for example, 
glReadPixels and glDrawPixels. These functions directly access the framebuffer and read 
or write data directly. Therefore, it is useful to be able not only to flush the buffer, but also 
to wait for all the commands to be executed before calling one of these functions. For this 
reason, you also do not put these commands in a display list. For example, if you render 
an image that you want to read back with glReadPixels, you could read the framebuffer 
before the command batch has even been flushed. To both force a flush and wait for the 
all previous rendering commands to finish, call the following function: 


void glFinish(void) ; 


Preprocessed Batches 

The work done every time you call an OpenGL command is not inconsequential. 
Commands are compiled, or converted, from OpenGL’s high-level command language into 
low-level hardware commands understood by the hardware. For complex geometry, or just 
large amounts of vertex data, this process is performed many thousands of times, just to 
draw a single image onscreen. Often, the geometry or other OpenGL data remains the 
same from frame to frame. A solution to this needlessly repeated overhead is to save a 
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chunk of data from the command buffer that performs some repetitive rendering task. 
This chunk of data can later be copied back to the command buffer all at once, saving the 
many function calls and compilation work done to create the data. 


OpenGL provides a facility to create a preprocessed set of OpenGL commands (the chunk 
of data) that can then be quickly copied to the command buffer for more rapid execution. 
This precompiled list of commands is called a display list, and creating one or more of 
them is an easy and straightforward process. Just as you delimit an OpenGL primitive with 
g1Begin/glEnd, you delimit a display list with g1NewList/glEndList. A display list, 
however, is named with an integer value that you supply. The following code fragment 
represents a typical example of display list creation: 


glNewList(<unsigned integer name>,GL_COMPILE) ; 
// Some OpenGL Code 


glEndList(); 


The named display list now contains all OpenGL rendering commands that occur between 
the glNewList and glEndList function calls. The GL_COMPILE parameter tells OpenGL to 
compile the list but not to execute it yet. You can also specify GL_COMPILE_AND_EXECUTE to 
simultaneously build the display list and execute the rendering instructions. Typically, 
however, display lists are built (GL_COMPILE only) during program initialization and then 
executed later during rendering. 


The display list name can be any unsigned integer. However, if you use the same value 
twice, the second display list overwrites the previous one. For this reason, it is convenient 
to have some sort of mechanism to keep you from reusing the same display list more than 
once. This is especially helpful when you are incorporating libraries of code written by 
someone else who may have incorporated display lists and may have chosen the same 
display list names. 


OpenGL provides built-in support for allocating unique display list names. The following 
function returns the first of a series of display list integers that are unique: 


GLuint glGenLists(GLsizei range) ; 
The display list names are reserved sequentially, with the first name being returned by the 
function. You can call this function as often as you want and for as many display list 


names at a time as you may need. A corresponding function frees display list names and 
releases any memory allocated for those display lists: 


void glDeleteLists(GLuint list, GLsizei range); 
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A display list, containing any number of precompiled OpenGL commands, is then 
executed with a single command: 


void glCallList(GLuint list); 


You can also execute a whole array of display lists with this command: 


void glCallLists(GLsizei n, GLenum type, const GLvoid *lists) ; 


The first parameter specifies the number of display lists contained by the array lists. The 
second parameter contains the data type of the array; typically, it is GL_UNSIGNED_BYTE. 


Display List Caveats 

A few important points about display lists are worth mentioning here. Although on most 
implementations, a display list should improve performance, your mileage may vary 
depending on the amount of effort the vendor puts into optimizing display list creation 
and execution. It is rare, however, for display lists not to offer a noticeable boost in perfor- 
mance, and they are widely relied on in applications that use OpenGL. 


Display lists are typically good at creating precompiled lists of OpenGL commands, espe- 
cially if the list contains state changes (turning lighting on and off, for example). If you do 
not create a display list name with glGenLists first, you might get a working display list 
on some implementations, but not on others. Some commands simply do not make sense 
in a display list. For example, reading the framebuffer into a pointer with glReadPixels 
makes no sense in a display list. Likewise, calls to g1TexImage2D would store the original 
image data in the display list, followed by the command to load the image data as a 
texture. Basically, your textures stored this way would take up twice as much memory! 
Display lists excel, however, at precompiled lists of geometry, with texture objects bound 
either inside or outside the display lists. Finally, display lists cannot contain calls that 
create display lists. You can have one display list call another, but you cannot put calls to 
glNewLists/glEndList inside a display list. 


Converting to Display Lists 


Converting the BOLT sample to use display lists requires only a few additional lines of 
code. First, we add three variables that contain the display list identifiers for the three 
pieces of the bolt: 


// Display list identifiers 

GLuint headList, shaftList, threadList; 

Then, in the SetupRC function, we request three display list names and assign them to our 
display list variables: 


// Get Display list names 
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headList = glGenLists(3) ; 
shaftList = headList + 1; 
threadList = headList + 2; 


Next, we add the code to generate the three display lists. Each display list simply calls the 
function that draws that piece of geometry: 


// Prebuild the display lists 

glNewList(headList, GL_COMPILE) ; 
RenderHead() ; 

glEndList(); 


glNewList(shaftList, GL_COMPILE) ; 
RenderShaft(); 
glEndList(); 


glNewList(threadList, GL_COMPILE) ; 
RenderThread(); 
glEndList(); 


Finally, in the Render function, we simply replace each function call for the bolt pieces 
with the appropriate display list call: 


// Render just the Thread of the nut 
//RenderShaft(); 
glCallList(shaftList) ; 


glPushMatrix(); 

glRotatef(-90.0f, 1.0f, 0.0f, 0.0f); 
//RenderThread() ; 
glCallList(threadList) ; 


glTranslatef(0.0f ,0.0f ,45.0f) ; 
//RenderHead() ; 
glCallList(headList) ; 


In this example, we have created three display lists, one for each component of the bolt. 
We also could have placed the entire bolt in a single display list or even created a fourth 
display list that contained calls to the other three. You can find the complete code for the 
display list version of the bolt in the BOLTDL sample program on the CD. 


Measuring Performance 


It is difficult to demonstrate the performance enhancements made by using display lists 
with something as simple as the BOLT example. To demonstrate the advantages of using 


567 


568 


CHAPTER 11 It’s All About the Pipeline: Faster Geometry Throughput 


display lists (or vertex arrays, for that matter), we need two things. First, we need a sample 
program with a more serious amount of geometry. Second, we need a way to measure 
performance besides some subjective measure of how fast an animation appears to be 
running. 


Most chapters have included a SPHEREWORLD sample program that demonstrates an 
immersive 3D environment, enhanced using techniques presented in that particular 
chapter. By this point in the book, the SphereWorld contains a lot of geometry. A highly 
tessellated ground and torus and a number of high-resolution spheres inhabit the plane. 
In addition, the planar shadow algorithm we used requires that nearly all the geometry be 
processed twice (once for the object, once for the shadow). Certainly, this sample program 
should see some visible benefit from a retrofit using display lists. 


A simple and meaningful measure of rendering performance is the measure of how many 
frames (individual images) can be rendered per second. In fact, many games and graphical 
benchmarking programs have options to display the frame rate prominently, as a frames 
per second (fps) indicator. For this chapter’s installment of SPHEREWORLD, we will add 
both a frame rate indication and the option to use or not use display lists. The difference 
measured in fps should give us a reasonable indication of the type of performance 
improvement that display lists can frequently contribute to our applications. 


The frame rate is simply the number of frames rendered over some period of time, divided 
by the amount of time elapsed. Counting buffer swaps is relatively simple...counting 
seconds, as it turns out, is not as easy as it sounds. High-resolution time keeping is unfor- 
tunately an operating system and hardware platform feature that is not very portable. 
Time-keeping functions are also documented poorly and can imply misleading perfor- 
mance characteristics. For example, most standard C runtime functions that can return 
time to the nearest millisecond often have a resolution of many, many milliseconds. 
Subtracting two times should give you the difference between events, but sometimes the 
minimum amount of time you can actually measure is as much as 1/20" of a second. With 
timer resolution this poor, you can sometimes render several frames and buffer swaps 
without being able to see any difference in time pass at all! 


The glTools library contains a time data structure and two time functions that isolate 
operating system dependencies and give fairly good timing resolution. On the PC, it is 
often on the order of millionths of a second, and on the Mac, you will get at least 10ms 
resolution. These functions work something like a stopwatch. In fact, the data structure 
that contains the last sampled time is defined as such: 


GLTStopwatch frameTimer; 
These next two functions reset the stopwatch and read the number of elapsed seconds (as 
a floating-point value) since the last time the stopwatch was reset: 


void gltStopwatchReset(GLTStopwatch *pTimer) ; 
float gltStopwatchRead(GLTStopwatch *pTimer) ; 
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You must reset the stopwatch at least one time before any read time values will have any 
meaning. 


A Better Example 


Because SPHEREWORLD is a fairly long program and has already been introduced in 
earlier chapters, Listing 11.5 shows only the new RenderScene function, which contains 
some noteworthy changes. 


LISTING 11.5. Main Rendering Function for SPHEREWORLD 


void RenderScene(void) 


{ 
static int iFrames = 0; // Frame count 
static GLTStopwatch frameTimer; // Render time 


// Reset the stopwatch on first time 
if(iFrames == 0) 
{ 
gltStopwatchReset (&frameTimer) ; 
iFrames++; 


} 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT |} GL_STENCIL_BUFFER_BIT); 


glPushMatrix(); 
gltApplyCameraTransform(&frameCamera) ; 


// Position light before any other transformations 
glLightfv(GL_LIGHT®, GL_POSITION, fLightPos) ; 


// Draw the ground 
glColor3f(1.0f, 1.0f, 1.0f); 
if(iMethod == 0) 
DrawGround() ; 
else 
glCallList(groundList) ; 


// Draw shadows first 
glDisable(GL_DEPTH_TEST) ; 
glDisable(GL_LIGHTING) ; 
glDisable(GL_TEXTURE_2D) ; 
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LISTING 11.5 Continued 


glEnable(GL_BLEND) ; 
glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) ; 
glEnable(GL_STENCIL_TEST) ; 
glPushMatrix(); 

glMultMatrixf (mShadowMatrix) ; 

DrawInhabitants (1); 
glPopMatrix(); 
glDisable(GL_STENCIL_TEST) ; 
glDisable(GL_BLEND) ; 
glEnable(GL_LIGHTING) ; 
glEnable(GL_TEXTURE_2D) ; 
glEnable(GL_DEPTH_TEST) ; 


// Draw inhabitants normally 
DrawInhabitants(Q) ; 


glPopMatrix(); 


// Do the buffer Swap 
glutSwapBuffers() ; 


// Increment the frame count 
iFrames++; 


// Do periodic frame rate calculation 
if(iFrames == 101) 

{ 

float fps; 

char cBuffer[64]; 


fps = 100.0f / gltStopwatchRead(&frameTimer) ; 
if(iMethod == @) 
sprintf (cBuffer, 
"OpenGL SphereWorld without Display Lists %.1f fps", fps); 
else 
sprintf (cBuffer, 
"OpenGL SphereWorld with Display Lists %.1f fps", fps); 


glutSetWindowTitle(cBuffer) ; 
gltStopwatchReset (&frameTimer) ; 
iFrames = 1; 
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LISTING 11.5 Continued 
} 


// Do it again 
glutPostRedisplay() ; 
} 


First, we have two static variables that will retain their values from one function call to the 
next. They are the frame counter and frame timer: 


static int iFrames = 0; // Frame count 
static GLTStopwatch frameTimer; // Render time 


Because the timer must be initialized before use, we use the frame counter as a sentinel. 
The iFrames variable contains only the value 0 the first time the scene is rendered, so here 
we perform the initial stopwatch reset: 


// Reset the stopwatch on first time 
if(iFrames == Q) 
{ 
gltStopwatchReset (&frameTimer) ; 
iFrames++; 


} 


Next, we render the scene almost as usual. Note this change to the place where the ground 
is drawn: 


if (iMethod == 0) 
DrawGround() ; 

else 
glCallList(groundList) ; 


The iMethod variable is set to 0 when the pop-up menu selection is Without Display Lists 
and 1 when With Display Lists is selected. A display list is generated in the SetupRC func- 
tion for the ground, the torus, and a sphere. The DrawInhabitants function, likewise, 
switches between the display list and base function call as indicated by the iMethod vari- 
able. After the buffer swap, we simply increment the frame counter: 


// Do the buffer Swap 
glutSwapBuffers(); 


// Increment the frame count 
iFrames++; 
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The frame rate is not calculated every single frame. Instead, we count some number of 
frames and then divide the total time by the number of frames. This approach serves two 
purposes. First, if the timer resolution is not terribly great, spreading out the time helps 
mitigate this problem by reducing the percentage of the total time represented by the 
error. Second, the process of calculating and displaying the frame rate takes time and will 
slow down the rendering, as well as adversely affect the accuracy of the measurement. 


When the frame counter reaches 101, we have rendered 100 frames (recall, we start at 1, 
not 0). So, we create a string buffer, fill it with our frame rate calculation, and simply pop 
it into the window title bar. Finally, we must reset the timer and our counter to 1: 


// Do periodic frame rate calculation 
if(iFrames == 101) 

{ 

float fps; 

char cBuffer[64]; 


fps = 100.0f / gltStopwatchRead(&frameTimer) ; 
if(iMethod == @) 
sprintf (cBuffer, 
"OpenGL SphereWorld without Display Lists %.1f fps", fps); 
else 
sprintf (cBuffer, 
"OpenGL SphereWorld with Display Lists %.1f fps", fps); 


glutSetWindowTitle(cBuffer) ; 
gltStopwatchReset (&frameTimer) ; 
iframes = 1; 


} 


Switching to display lists can have an amazing impact on performance. Some OpenGL 
implementations even try to store display lists in memory on the graphics card, if possi- 
ble, further reducing the work required to get the data to the graphics processor. Figure 
11.7 shows the SPHEREWORLD sample running without using display lists. The frame rate 
is fairly high already on a modern consumer graphics card. However, in Figure 11.8, you 
can see the frame rate is far and away higher. 


Why should you care about rendering performance? The faster and more efficient your 
rendering code, the more visual complexity you can add to your scene without dragging 
down the frame rate too much. Higher frame rates yield smoother and better-looking 
animations. You can also use the extra CPU time to perform other tasks such as physics 
calculations or lengthy I/O operations on a separate thread. 
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FIGURE 11.7. SPHEREWORLD without display lists. 


FIGURE 11.8 | SPHEREWORLD with display lists. 
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Display lists are frequently used for precompiling sets of OpenGL commands. In our BOLT 
example, display lists were perhaps a bit underused because all we really encapsulated was 
the creation of the geometry. In the same vein, SphereWorld’s many spheres required a 
great deal of trigonometric calculations saved by placing the geometry in display lists. You 
might consider that we could just as easily have created some arrays to store the vertex 
data for the models and thus saved all the computation time just as easily as with the 
display lists. 


You might be right about this way of thinking—to a point. Some implementations store 
display lists more efficiently than others, and if all you're really compiling is the vertex 
data, you can simply place the model's data in one or more arrays and render from the 
array of precalculated geometry. The only drawback to this approach is that you must still 
loop through the entire array moving data to OpenGL one vertex at a time. Depending on 
the amount of geometry involved, taking this approach could be a substantial perfor- 
mance penalty. The advantage, however, is that, unlike with display lists, the geometry 
does not have to be static. Each time you prepare to render the geometry, some function 
could be applied to all the geometry data and perhaps displace or modify it in some way. 
For example, say a mesh used to render the surface of an ocean could have rippling waves 
moving across the surface. A swimming whale or jellyfish could also be cleverly modeled 
with deformable meshes in this way. 


With OpenGL, you can, in fact, have the best of both scenarios by using vertex arrays. 
With vertex arrays, you can precalculate or modify your geometry on the fly, but do a bulk 
transfer of all the geometry data at one time. Basic vertex arrays can be almost as fast as 
display lists, but without the requirement that the geometry be static. It might also simply 
be more convenient to store your data in arrays for other reasons and thus also render 
directly from the same arrays (this approach could also potentially be more memory effi- 
cient). 


Using vertex arrays in OpenGL involves four basic steps. First, you must assemble your 
geometry data in one or more arrays. You can do this algorithmically or perhaps by 
loading the data from a disk file. Second, you must tell OpenGL where the data is. When 
rendering is performed, OpenGL pulls the vertex data directly from the arrays you have 
specified. Third, you must explicitly tell OpenGL which arrays you are using. You can have 
separate arrays for vertices, normals, colors, and so on, and you must let OpenGL know 
which of these data sets you want to use. Finally, you execute the OpenGL commands to 
actually perform the rendering using your vertex data. 


To demonstrate these four steps, we revisit an old sample from another chapter. We’ve 
rewritten the SMOOTHER sample from Chapter 6 for the STARFIELD sample in this 
chapter. The STARFIELD sample creates three arrays that contain randomly initialized posi- 
tions for stars in a starry sky. We then use vertex arrays to render directly from these 
arrays, bypassing the glBegin/glEnd mechanism entirely. Figure 11.9 shows the output of 
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the STARFIELD sample program, and Listing 11.6 shows the important portions of the 


source code. 


FIGURE 11.9 Output from the STARFIELD program. 


LISTING 11.6 Setup and Rendering Code for the STARFIELD Sample 


// Array of small stars 
#define SMALL_STARS 150 
GLTVector2 vSmallStars[SMALL_STARS]; 


#define MEDIUM_STARS 40 
GLTVector2 vMediumStars[MEDIUM_STARS] ; 


#define LARGE_STARS 15 
GLTVector2 vLargeStars[LARGE_STARS]; 


#define SCREEN_X 800 
#define SCREEN_Y 600 
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LISTING 11.6 Continued 


// This function does any needed initialization on the rendering 
// context. 
void SetupRC() 

{ 


int i; 


// Populate star list 
for(i = 0; i < SMALL_STARS; i++) 


{ 

vSmallStars[i][@] = (GLfloat)(rand() % SCREEN_X); 
vSmallStars[i][1] = (GLfloat)(rand() % (SCREEN_Y - 100))+100.0f; 
} 


// Populate star list 

for(i = @; i < MEDIUM_STARS; i++) 
{ 
vMediumStars[i][®] = (GLfloat)(rand() % SCREEN_X * 10)/10.0f; 
vMediumStars[i][1] (GLfloat)(rand() % (SCREEN_Y - 100))+100.0f; 
} 


// Populate star list 
for(i = 0; i < LARGE_STARS; i++) 
{ 
vLargeStars[i][@] = (GLfloat)(rand() % SCREEN_X*10)/10.0f; 
vLargeStars[i][1] = 
(GLfloat)(rand() % (SCREEN_Y - 100)*10.0f)/ 10.0f +100.0f; 
} 


// Black background 
glClearColor(0.0f, 0.0f, 0.O0f, 1.0f ); 


// Set drawing color to white 
glColor3f(@.0f, 0.0f, 0.0f); 
} 


PUTTTTTTTTTT TTT TT TL 
// Called to draw scene 
void RenderScene(void) 


{ 
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LISTING 11.6 Continued 


// 
// 
// 
// 
// 


GLfloat x = 700.0f; // Location and radius of moon 
GLfloat y = 500.0f; 

GLfloat r = 50.0f; 

GLfloat angle = 0.0f; // Another looping variable 


// Clear the window 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 


// Everything is white 
glColor3f(1.0f, 1.0f, 1.0f); 


// Using vertex arrays 
glEnableClientState(GL_VERTEX_ARRAY) ; 


// Draw small stars 
glPointSize(1.0f); 
This code is no longer needed 
glBegin(GL_POINTS) ; 
for(i = @; i < SMALL_STARS; i++) 
glVertex2fv(vSmallStars[i]); 
glEnd() ; 


// Newer vertex array functionality 
glVertexPointer(2, GL_FLOAT, 0, vSmallStars) ; 
glDrawArrays(GL_POINTS, @, SMALL_STARS) ; 


// Draw medium sized stars 

glPointSize(3.05f) ; 

glVertexPointer(2, GL_FLOAT, ®, vMediumStars) ; 
glDrawArrays(GL_POINTS, @, MEDIUM_STARS) ; 


// Draw largest stars 

glPointSize(5.5f) ; 

glVertexPointer(2, GL_FLOAT, @, vLargeStars) ; 
glDrawArrays(GL_POINTS, @, LARGE_STARS) ; 


// Draw the "moon" 
glBegin(GL_TRIANGLE_FAN) ; 
glVertex2f(x, y); 
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LISTING 11.6 Continued 


for(angle = @; angle < 2.0f * 3.141592f; angle += 0.1f) 
glVertex2f(x + (float)cos(angle) * r, y + (float)sin(angle) * r); 
glVertex2f(x +r, y); 
glEnd(); 


// Draw distant horizon 
glLineWidth(3.5) ; 
glBegin(GL_LINE_STRIP) ; 
glVertex2f(0.0f, 25.0f); 
glVertex2f(50.0f, 100.0f); 
glVertex2f(100.0f, 25.0f); 
glVertex2f(225.0f, 125.0f); 
glVertex2f (300.0f, 50.0f); 
glVertex2f(375.0f, 100.0f); 
glVertex2f (460.0f, 25.0f); 
glVertex2f(525.0f, 100.0f); 
glVertex2f(600.0f, 20.0f); 
glVertex2f(675.0f, 70.0f); 
glVertex2f(750.0f, 25.0f); 
glVertex2f (800.0f, 90.0f); 
glEnd(); 


// Swap buffers 
glutSwapBuffers() ; 
} 


Loading the Geometry 

The first prerequisite to using vertex arrays is that your geometry must be stored in arrays. 
In Listing 11.6, you see three globally accessible arrays of two-dimensional vectors. They 
contain x and y coordinate locations for the three groups of stars: 


// Array of small stars 
#define SMALL_STARS 150 
GLTVector2 vSmallStars[SMALL_STARS] ; 


#define MEDIUM_STARS 40 
GLTVector2 vMediumStars[MEDIUM_STARS] ; 


#define LARGE_STARS 15 
GLTVector2 vLargeStars[LARGE_STARS] ; 
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Recall that this sample program uses an orthographic projection and draws the stars as 
points at random screen locations. Each array is populated in the SetupRC function with a 
simple loop that picks random x and y values that fall within the portion of the window 
we want the stars to occupy. The following few lines from the listing show how just the 
small star list is populated: 


// Populate star list 
for(i = 0; i < SMALL_STARS; i++) 


{ 

vSmallStars[i][0] = (GLfloat)(rand() % SCREEN_X); 
vSmallStars[i][1] = (GLfloat)(rand() % (SCREEN_Y - 100))+100.0f; 
} 


Enabling Arrays 


In the RenderScene function, we enable the use of an array of vertices with the following 
code: 


// Using vertex arrays 
glEnableClientState(GL_VERTEX_ARRAY) ; 


This is the first new function for using vertex arrays, and it has a corresponding disabling 
function: 


void glEnableClientState(GLenum array); 
void glDisableClientState(GLenum array); 


These functions accept the following constants, turning on and off the corresponding 
array usage: GL_VERTEX_ARRAY, GL_COLOR_ARRAY, GL_SECONDARY_COLOR_ARRAY, 
GL_NORMAL_ARRAY, GL_FOG_COORDINATE_ARRAY, GL_TEXURE_COORD_ARRAY, and 
GL_EDGE_FLAG_ARRAY. For our STARFIELD example, we are sending down only a list of 
vertices. As you can see, you can also send down a corresponding array of normals, texture 
coordinates, colors, and so on. 


Here’s one question that commonly arises with the introduction of this function: Why did 
the OpenGL designers add a new glEnableClientState function instead of just sticking 
with glEnable. A good question. The reason has to do with how OpenGL is designed to 
operate. OpenGL was designed using a client/server model. The server is the graphics 
hardware, and the client is the host CPU and memory. On the PC, for example, the server 
would be the graphics card, and the client would be the PC’s CPU and main memory. 
Because this state of enabled/disabled capability specifically applies to the client side of 
the picture, a new set of functions was derived. 
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Where’s the Data? 


Before we can actually use the vertex data, we must still tell OpenGL where to fetch the 
data. The following single line in the STARFIELD example does this: 


glVertexPointer(2, GL_FLOAT, 0, vSmallStars) ; 


Here, we find our next new function. The glVertexPointer function tells OpenGL where 
it can fetch the vertex data. There are also corresponding functions for the other types of 
vertex array data: 


void glVertexPointer(GLint size, GLenum type, GLsizei stride, 

const void *pointer); 
void glColorPointer(GLint size, GLenum type, GLsizei stride, 

const void *pointer) ; 
void glTexCoordPointer(GLint size, GLenum type, GLsizei stride, 

const void *pointer) ; 
void glSecondaryColorPointer(GLint size, GLenum type, GLsizei stride, 

const void *pointer); 
void glNormalPointer(GLenum type, GLsizei stride, const void *pData); 


void glFogCoordPointer(GLenum type, GLsizei stride, const void *pointer) ; 
void glEdgeFlagPointer(GLenum type, GLsizei stride, const void *pointer) ; 


These functions are all closely related and take nearly identical arguments. All but the 
normal, fog coordinate, and edge flag functions take a size argument first. This argument 
tells OpenGL the number of elements that make up the coordinate type. For example, 
vertices can consist of 2 (x,y), 3 (x,y,z), or 4 (x,y,z,w) components. Normals, however, are 
always three components, and fog coordinates and edge flags are always one component; 
thus, it would be redundant to specify the argument for these arrays. 


The type parameter specifies the OpenGL data type for the array. Not all data types are 
valid for all vertex array specifications. Table 11.1 lists the seven vertex array functions 
(index pointers are used for color index mode and are thus excluded here) and the valid 
data types that can be specified for the data elements. 


TABLE 11.1 Valid Vertex Array Sizes and Data Types 


Command Elements Valid Data Types 


glColorPointer 3,4 GL_BYTE, GL_UNSIGNED BYTE, GL_SHORT, 
GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, 
GL_FLOAT, GL_DOUBLE 

glEdgeFlagPointer 1 None specified (always GLboolean) 
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Command Elements Valid Data Types 

glFogCoordPointer 1 GL_FLOAT, GL_DOUBLE 

glNormalPointer 3 GL_BYTE, GL_SHORT, GL_INT, GL_FLOAT, GL_DOUBLE 

glSecondaryColorPointer 2 GL_BYTE, GL_UNSIGNED_BYTE, GL_SHORT, GL_INT, 
GL_UNSIGNED_INT, GL_FLOAT, GL_DOUBLE 

glTexCoordPointer Veep oe GL_SHORT, GL_INT, GL_FLOAT, GL_DOUBLE 

glVertexPointer 2, 3,4 GL_SHORT, GL_INT, GL_FLOAT, GL_DOUBLE 


The stride parameter specifies the space in bytes between each array element. Typically, 
this value is just 0, and array elements have no data gaps between values. Finally, the 
parameter is a pointer to the array of data. For arrays, this is simply the name of the array. 


Draw! 


Finally, we’re ready to render using our vertex arrays. We can actually use the vertex arrays 
in two different ways. For illustration, first look at the nonvertex array method that 
simply loops through the array and passes a pointer to each array element to glVertex: 


glBegin(GL_POINTS) ; 
for(i = 0; i < SMALL_STARS; i++) 
glVertex2fv(vSmallStars[i]); 
glEnd(); 


Because OpenGL now knows about our vertex data, we can have OpenGL look up the 
vertex values for us with the following code: 


glBegin(GL_POINTS) ; 
for(i = 0; i < SMALL_STARS; i++) 
glArrayElement (i) ; 
glEnd(); 


The glArrayElement function looks up the corresponding array data from any arrays that 
have been enabled with glEnableClientState. If an array has been enabled, and a corre- 
sponding array has not been specified (g1VertexPointer, glColorPointer, and so on), an 
illegal memory access will likely cause the program to crash. The advantage to using 
glArrayElement is that a single function call can now replace several function calls 
(glNormal, glColor, glVertex, and so forth) needed to specify all the data for a specific 
vertex. Sometimes you might want to jump around in the array in nonsequential order as 
well. 
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Most of the time, however, you will find that you are simply transferring a block of vertex 
data that needs to be traversed from beginning to end. In these cases (as is the case with 
the STARFIELD sample), OpenGL can transfer a single block of any enabled arrays with a 
single function call: 


void glDrawArrays(GLenum mode, GLint first, GLint count); 


In this function, mode specifies the primitive to be rendered (one primitive batch per func- 
tion call). The first parameter specifies where in the enabled arrays to begin retrieving 
data, and the count parameter tells how many array elements to retrieve. In the case of 
the STARFIELD example, we rendered the array of small stars as follows: 


glDrawArrays(GL_POINTS, @, SMALL_STARS); 


OpenGL implementations can optimize these block transfers, resulting in significant 
performance gains over multiple calls to the individual vertex functions such as glVertex, 
glNormal, and so forth. 


Indexed Vertex Arrays 


Indexed vertex arrays are vertex arrays that are not traversed in order from beginning to 
end, but are traversed in an order that is specified by a separate array of index values. This 
may seem a bit convoluted, but actually indexed vertex arrays can save memory and 
reduce transformation overhead. Under ideal conditions, they can actually be faster than 
display lists! 


The reason for this extra efficiency is the array of vertices can be smaller than the array of 
indices. Adjoining primitives such as triangles can share vertices in ways not possible by 
just using triangle strips or fans. For example, using ordinary rendering methods or vertex 
arrays, there is no other mechanism to share a set of vertices between two adjacent trian- 
gle strips. Figure 11.10 shows two triangle strips that share one edge. Although triangle 
strips make good use of shared vertices between triangles in the strip, there is no way to 
avoid the overhead of transforming the vertices shared between the two strips because 
each strip must be specified individually. 


Now let’s look at a simple example; then we’ll look at a more complex model and examine 
the potential savings of using indexed arrays. 


A Simple Cube 

In the thread example, we repeated many normals and vertices. We can save a consider- 
able amount of memory if we can reuse a normal or vertex in a vertex array without 
having to store it more than once. Not only is memory saved, but also a good OpenGL 
implementation is optimized to transform these vertices only once, saving valuable trans- 
formation time. 
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Strip 1 
Shared vertices 


Strip 2 


FIGURE 11.10 Two triangle strips in which the vertices share an edge. 


Instead of creating a vertex array containing all the vertices for a given geometric object, 
you can create an array containing only the unique vertices for the object. Then you can 
use another array of index values to specify the geometry. These indices reference the 
vertex values in the first array. Figure 11.11 shows this relationship. 


Index Array 


FIGURE 11.11 — An index array referencing an array of unique vertices. 


Each vertex consists of three floating-point values, but each index is only an integer value. 
A float and an integer are 4 bytes on most machines, which means you save 8 bytes for 
each reused vertex for the cost of 4 extra bytes for every vertex. For a small number of 
vertices, the savings might not be great; in fact, you might even use more memory using 
an indexed array than you would have by just repeating vertex information. For larger 
models, however, the savings can be substantial. 


Figure 11.12 shows a cube with each vertex numbered. For our next sample program, 
CUBEDX, we create a cube using indexed vertex arrays. 
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FIGURE 11.12 A cube containing six unique numbered vertices. 


Listing 11.7 shows the code from the CUBEDX program to render the cube using indexed 
vertex arrays. The six unique vertices are in the corners array, and the indices are in the 
indexes array. In RenderScene, we set the polygon mode to GL_LINE so that the cube is 
wireframed. 


LISTING 11.7 Code from the CUBEDX Program to Use Indexed Vertex Arrays 


// Array containing the six vertices of the cube 
static GLfloat corners[] = { -25.0f, 25.0f, 25.0f, // 0 
25.0f, 25.0f, 25.0f, // 1 
25.0f, -25.0f, 25.0f,// 2 
-25.0f, -25.0f, 25.0f,// 3 
4 
5 


// Front of cube 


-25.0f, 25.0f, -25.0f,// 
25.0f, 25.0f, -25.0f,// 
25.0f, -25.0f, -25.0f,// 6 
-25.0f, -25.0f, -25.0f }3// 7 


// Back of cube 


// Array of indexes to create the cube 


static GLubyte indexes[] = { ®, 1, 2, 3, // Front Face 
455. hy (Os // Top Face 
Se egg ts // Bottom Face 
55145 37.406 // Back Face 
1,; 5, 6, 2; // Right Face 
4, 0.3, 7%}; Jb Left. Face 


// Rotation amounts 
static GLfloat xRot 
static GLfloat yRot 


0.0f; 
Q.0f; 
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LISTING 11.7 Continued 


// Called to draw scene 

void RenderScene(void) 
{ 
// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT ! GL_DEPTH_BUFFER_BIT); 


// Make the cube a wire frame 
glPolygonMode(GL_FRONT_AND_BACK, GL_LINE); 


// Save the matrix state 
glMatrixMode(GL_MODELVIEW) ; 
glPushMatrix(); 

glTranslatef(@.0f, @.0f, -200.0f); 


// Rotate about x and y axes 
glRotatef(xRot, 1.0f, 0.0f, 0.Of); 
glRotatef(yRot, @.0f, 0.0f, 1.0f); 


// Enable and specify the vertex array 
glEnableClientState(GL_VERTEX_ARRAY) ; 
glVertexPointer(3, GL_FLOAT, 0, corners); 


// Using Drawarrays 
glDrawElements(GL_QUADS, 24, GL_UNSIGNED_BYTE, indexes) ; 


glPopMatrix(); 


// Swap buffers 
glutSwapBuffers(); 
} 


OpenGL has native support for indexed vertex arrays, as shown in the g1DrawElements 
function. The key line in Listing 11.7 is 


glDrawElements(GL_QUADS, 24, GL_UNSIGNED_ BYTE, indexes) ; 
This line is much like the g1DrawArrays function mentioned earlier, but now we are speci- 


fying an index array that determines the order in which the enabled vertex arrays are 
traversed. Figure 11.13 shows the output from the program CUBEDX. 
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FIGURE 11.13 A wireframe cube drawn with an indexed vertex array. 


A variation on glDrawElement is the g1DrawRangeElements function. This function is docu- 
mented in the reference section and simply adds two parameters to specify the range of 
indices that will be valid. This hint can enable some OpenGL implementations to prefetch 
the vertex data, a potentially worthwhile performance optimization. A further enhance- 
ment is gl1MultiDrawArrays, which allows you to send multiple arrays of indices with a 
single function call. 


One last vertex array function you'll find in the reference section is glInterleavedArrays. 
It allows you to combine several arrays into one aggregate array. There is no change to 
your access or traversal of the arrays, but the organization in memory can possibly 
enhance performance on some hardware implementations. 


Getting Serious 

With a few simple examples behind us, it’s time to tackle a more sophisticated model with 
more vertex data. For this example, we use a model created by Full Sail student Stephen 
Carter, generously provided by the school’s gaming department. We also use a product 
called Deep Exploration from Right Hemisphere that has a handy feature of exporting 
models as OpenGL code! A demo version of this product is available on the CD with this 
book. Figure 11.14 shows Deep Exploration running and displaying the model that we will 
be working with. 
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FIGURE 11.14 Sample model to be rendered with OpenGL. 


We had to modify the code output by Deep Exploration so that it would work with our 
GLUT framework and run on both the Macintosh and PC platforms. You can find the code 
that renders the model in the MODELTEST sample program. We do not include the entire 
program listing here because it is quite lengthy and mostly meaningless to human beings. 
It consists of a number of arrays representing 2,248 individual triangles (that’s a lot of 
numbers to stare at!). 


The approach taken with this tool is to produce the smallest possible amount of code to 
represent the given model. Deep Exploration has done an excellent job of compacting the 
data. There are 2,248 individual triangles, but using a clever indexing scheme, Deep 
Exploration has encoded this as only 1,254 individual vertices, 1,227 normals, and 2,141 
texture coordinates. The following code shows the DrawModel function, which loops 
through the index set and sends OpenGL the texture, normal, and vertex coordinates for 
each individual triangle: 


void DrawModel (void) 
{ 
int iFace, iPoint; 
glBegin(GL_TRIANGLES) ; 
for(iFace = 0; iFace < 2248; iFacet+) // Each new triangle starts here 
for(iPoint = @; iPoint < 3; iPoint++) // Each vertex specified here 


{ 
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// Lookup the texture value 
glTexCoord2fv(textures[face_indices[iFace] [iPoint+6]]); 


// Lookup the normal value 
glNormal3fv(normals[face_indices[iFace] [iPoint+3]]) ; 


// Lookup the vertex value 
glVertex3fv(vertices[face_indices[iFace][iPoint]]); 
} 

glEnd(); 

} 


This approach is ideal when you must optimize the storage size of the model data—for 
example, to save memory in an embedded application, reduce storage space, or reduce 
bandwidth if the model must be transmitted over a network. However, for real-time appli- 
cations where performance considerations can sometimes outweigh memory constraints, 
this code would perform quite poorly because once again you are back to square one, 
sending vertex data to OpenGL one vertex at a time. 


The simplest and perhaps most obvious approach to speeding up this code is simply to 
place the DrawModel function in a display list. Indeed, this is the approach we used in the 
MODELTEST program that renders this model. Let’s look at the cost of this approach and 
compare it to rendering the same model with indexed vertex arrays. 


Measuring the Cost First, we calculate the amount of memory required to store the origi- 
nal compacted vertex data. We can do this simply by looking at the declarations of the 
data arrays and knowing how large the base data type is: 


static short face_indices[2248][9] = { .. 
static GLfloat vertices [1254][3] = { .. 
static GLfloat normals [1227][3] = { .. 
static GLfloat textures [2141][2] = { .. 


The memory for face_indices would be sizeof (short) x 2,248 x 9, which works out to 
40,464 bytes. Similarly, we calculate the size of vertices, normals, and textures as 15,048, 
14,724, and 17,128 bytes, respectively. This gives us a total memory footprint of 87,364 
bytes or about 85KB. 


But wait! When we draw the model into the display list, we copy all this data again into 
the display list, except that now we decompress our packed data so that many vertices are 
duplicated for adjacent triangles. We, in essence, undo all the work to optimize the storage 
of the geometry to draw it. We can’t calculate exactly how much space the display list 
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takes, but we can get a good estimate by calculating just the size of the geometry. There 
are 2,248 triangles. Each triangle has three vertices, each of which has a floating-point 
vertex (three floats), normal (three floats), and texture coordinate (two floats). Assuming 
four bytes for a float (sizeof (float)), we calculate this as follows: 


2,248 (triangle) x 3 (vertices) = 6,744 vertices. 


Each vertex has three components (x, y, 2): 


6,744 x 3 = 20,232 floating-point values for geometry. 


Each vertex has a normal, meaning three more components: 


6,744 x 3 = 20,232 floating-point values for normals. 


Each vertex has a texture, meaning two more components: 


6,744 x 2 = 13,488 floating-point values for texture coordinates. 


This gives a total of 53,952 floats, at 4 bytes each = 215,808 bytes. 


Total memory for the display list data and the original data is 311,736 bytes, just a tad 
more than 300KB. But don’t forget the transformation cost—6,744 (2,248 x 3) vertices 
must be transformed by the OpenGL geometry pipeline. That’s a lot of matrix multiplies! 


Creating a Suitable Indexed Array Just because the data in the MODELTEST sample is 
stored in arrays does not mean the data is ready to be used as any kind of OpenGL vertex 
array. In OpenGL, the vertex array, normal array, texture array, and any other arrays that 
you want to use must all be the same size. The reason is that all the array elements across 
arrays must be shared. For ordinary vertex arrays, as you march through the set of arrays, 
array element 0 from the vertex array must go with array element 0 from the normal 
array, and so on. For indexed arrays, we have the same limitation. Each index must 
address all the enabled arrays at the same corresponding array element. 


For the sample program MODELIVA, we wrote a function that goes through the existing 
vertex array and reindexes the triangles so that all three arrays are the same size and all 
array elements correspond exactly one to another. The pertinent code is given in 

Listing 11.8. 


LISTING 11.8 Code to Create a New Indexed Vertex Array 


TITTLE 
// These are hard coded for this particular example 

GLushort uilndexes[2248*3]; // Maximum number of indexes 
GLfloat vVerts[2248*3][3]; // (Worst case scenario) 

GLfloat vText[2248*3][2]; 
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LISTING 11.8 Continued 


GLfloat vNorms[2248*3][3]; 
int iLastIndex = Q; // Number of indexes actually used 


PETTTTTTTT TTT TTT ATT TT TTL 
// Compare two floating point values and return true if they are 
// close enough together to be considered the same. 
inline bool IsSame(float x, float y, float epsilon) 
{ 
if (fabs(x-y) < epsilon) 
return true; 


return false; 


} 


TITTTTTTTTTT TTT TTT TTT TTT TT TAT TL 
// Goes through the arrays and looks for duplicate vertices 
// that can be shared. This expands the original array somewhat 
// and returns the number of true unique vertices that now 
// populate the vVerts array. 
int IndexTriangles(void) 

{ 

int iFace, iPoint, iMatch; 

float e = 0.000001; // How small a difference to equate 


// LOOP THROUGH all the faces 
int iIndexCount = 0; 
for(iFace = 0; iFace < 2248; iFace++) 
{ 
for(iPoint = 0; iPoint < 3; iPoint++) 
{ 
// Search for match 
for(iMatch = 0; iMatch < iLastIndex; iMatch++) 
{ 
// If Vertex is the same... 
if (IsSame(vertices[face_indices[iFace][iPoint]][Q], 
vwerts[iMatch][0], e) && 
IsSame(vertices[face_indices[iFace][iPoint]][1], 
vwerts[iMatch][1], e) && 
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IsSame(vertices[face_indices[iFace][iPoint]][2], 
vwverts[iMatch][2], e) && 


LL 


// AND the Normal is the same... 
IsSame(normals[face_indices[iFace][iPoint+3]][0], 
vNorms[iMatch][@], e) && 
IsSame(normals[face_indices[iFace][iPoint+3]][1], 
vNorms[iMatch][1], e) && 
IsSame(normals[face_indices[iFace][iPoint+3]][2], 
vNorms[iMatch][2], e) && 


// And Texture is the same... 

IsSame(textures[face_indices[iFace] [iPoint+6]][], 
vText[iMatch][@], e) && 

IsSame(textures[face_indices[iFace][iPoint+6]][1], 
vText[iMatch][1], e)) 

{ 

// Then add the index only 

uiIndexes[iIndexCount] = iMatch; 

iIndexCount++; 

break; 


} 


// No match found, add this vertex to the end of our list, 
// and update the index array 
if(iMatch == iLastIndex) 
if 
// Add data and new index 
memcpy(vVerts[iMatch], vertices[face_indices[iFace][iPoint]], 
sizeof(float) * 3); 
memcpy(vNorms[iMatch], normals[face_indices[iFace][iPoint+3]], 
sizeof(float) * 3); 
memcpy(vText[iMatch], textures[face_indices[iFace][iPoint+6]], 
sizeof(float) * 2); 
uiIndexes[iIndexCount] = iLastIndex; 
iIndexCount++; 
iLastIndex++; 
} 
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LISTING 11.8 Continued 


return iIndexCount; 


} 


FITTTTTTT TTT TTT TAT TTT Th tk 
// Function to stitch the triangles together 
// and draw the vehicle 
void DrawModel(void) 

{ 

static int ilIndexes = 0; 

char cBuffer[32]; 


// The first time this is called, reindex the triangles. Report the results 
// in the window title 
if (iIndexes == Q) 
{ 
ilndexes = IndexTriangles(); 
sprintf (cBuffer,"Verts = %d Indexes = %d", iLastIndex, ilIndexes) ; 
glutSetWindowTitle(cBuffer) ; 
} 


// Use vertices, normals, and texture coordinates 
glEnableClientState(GL_VERTEX_ARRAY) ; 
glEnableClientState(GL_NORMAL_ARRAY) ; 
glEnableClientState(GL_TEXTURE_COORD_ARRAY) ; 


// Here's where the data is now 
glVertexPointer(3, GL_FLOAT,®, vVerts); 
glNormalPointer(GL_FLOAT, ®, vNorms) ; 
glTexCoordPointer(2, GL_FLOAT, 0, vText); 


// Draw them 
glDrawElements(GL_TRIANGLES, iIndexes, GL_UNSIGNED_SHORT, uilndexes) ; 
} 


First, we need to declare storage for our new indexed vertex array. Because we don’t know 
ahead of time what our savings will be, or indeed whether there will be any savings, we 
allocate a block of arrays assuming the worst case scenario. If each vertex is unique, three 
floats for each vertex (which is 2,248 faces x 3 vertices each): 


GLushort uiIndexes[2248*3] ; // Maximum number of indexes 
GLfloat vVerts[2248*3][3]; // (Worst case scenario) 
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GLfloat vText[2248*3] [2]; 
GLfloat vNorms[2248*3][3]; 
int iLastIndex = 0; // Number of indexes actually used 


Looking for duplicates requires us to test many floating-point values for equality. This is 
usually a no-no because floats are notoriously noisy; their values can float around and 
vary slightly (forgive the pun!). You frequently can solve this problem by writing a special 
function that simply subtracts two floats and seeing whether the difference is small 
enough to call it even: 


inline bool IsSame(float x, float y, float epsilon) 
{ 
if (fabs(x-y) < epsilon) 
return true; 


return false; 


} 


The IndexTriangles function is called only once; it goes through the existing array 
looking for duplicate vertices. For a vertex to be shared, all the vertex, normal, and texture 
coordinates must be exactly the same. If a match is found, that vertex is simply referenced 
in the new index array. If not, it is added to the end of the array of unique vertices and 
then referenced in the index array. 


In the DrawModel function, the IndexTriangles function is called (only once), and the 
window caption reports how many unique vertices were identified and how many indices 
are needed to traverse the list of triangles: 


// The first time this is called, reindex the triangles. Report the results 
// in the window title 
if (iIndexes == Q) 
{ 
iIndexes = IndexTriangles(); 
sprintf (cBuffer,"Verts = %d Indexes = %d", iLastIndex, iIndexes); 
glutSetWindowTitle(cBuffer) ; 
} 


From here, rendering is straightforward. You enable the three sets of arrays: 


// Use vertices, normals, and texture coordinates 
glEnableClientState(GL_VERTEX_ARRAY) ; 
glEnableClientState(GL_NORMAL_ARRAY) ; 
glEnableClientState(GL_TEXTURE_COORD_ARRAY) ; 
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Next, you tell OpenGL where the data is: 


// Here's where the data is now 
glVertexPointer(3, GL_FLOAT,@, vVerts) ; 
glNormalPointer(GL_FLOAT, ®, vNorms) ; 
glTexCoordPointer(2, GL_FLOAT, 0, vText); 


Then you fire off all the triangles: 


// Draw them 
glDrawElements(GL_TRIANGLES, iIndexes, GL_UNSIGNED_SHORT, uilndexes) ; 


Avoiding triangles for rendering might appear strange because they don’t have the shared 
vertex advantage of strips and fans. However, with indexed vertex arrays, we can go back 
to large batches of triangles and still have the advantage of multiple shared vertex data— 
perhaps even beating the efficiency offered by strips and fans. 


The final output of MODELIVA is shown in Figure 11.15. 
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FIGURE 11.15 A model rendered with indexed vertex arrays. 


Vertex Arrays 


Comparing the Cost Now let’s compare the cost of our two methods of rendering this 
model. From the output of the MODELIVA program, we see that 3,193 unique vertices 
were found; they can also share normals and texture coordinates. Rendering the entire 
model requires 6,744 indices still (this should come as no surprise!). 


Each vertex has three components (x,y,z): 


3,193 vertices x 3 = 9,579 floats 


Each normal also has three components: 


3,193 normals x 3 = 9,579 floats 


Each texture coordinate has two components: 
3,193 texture coordinates x 2 = 6,386 floats 
Multiplying each float by 4 bytes yields a memory overhead of 102,176 bytes. We still 


need to add in the index array of shorts. That’s 6,744 elements times 2 bytes each = 
13,488. This gives a grand total storage overhead of 115,664 bytes. 


Table 11.2 shows these values side by side. 


TABLE 11.2 Memory and Transformation Overhead for Three Rendering Methods 


Rendering Mode Memory Vertices 
Immediate Mode 95KB 6,744 
Display List 300KB 6,744 
Indexed Vertex Array 112KB 3,193 


You can see that the immediate mode rendering used by the code output by Deep 
Exploration certainly has the smallest memory footprint. However, this transfers the 
geometry to OpenGL very slowly. If you put the immediate mode code into a display list, 
the geometry transfer takes place much faster, but the memory overhead for the model 
soars to three times that originally required. The indexed vertex array seems a good 
compromise at just more than twice the memory footprint, but less than half the transfor- 
mation cost. 


Of course, in this example, we actually allocated a much larger buffer to hold the 
maximum number of vertices that may have been required. In a production program, you 
might have tools that take this calculated indexed array and write it out to disk with a 
header that describes the required array dimensions. Reading this model back into the 
program then is a simple implementation of a basic model loader. The loaded model is 
then exactly in the format required by OpenGL. 
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Models with sharp edges and corners often have fewer vertices that are candidates for 
sharing. However, models with large smooth surface areas can stand to gain even more in 
terms of memory and transformation savings. With the added savings of less geometry to 
move through memory, and the corresponding savings in mathematical operations, 
indexed vertex arrays can sometimes dramatically outperform display lists, even for static 
geometry. For many real-time applications, indexed vertex arrays are often the method of 
choice for geometric rendering. 


Summary 


In this chapter, we slowed down the pace somewhat and just explained how to build a 
three-dimensional object, starting with using the OpenGL primitives to create simple 3D 
pieces and then assembling them into a larger and more complex object. Learning the API 
is the easy part, but your level of experience in assembling 3D objects and scenes will be 
what differentiates you from your peers. After you break down an object or scene into 
small and potentially reusable components, you can save building time by using display 
lists. You’ll find many more functions for utilizing and managing display lists in the refer- 
ence section. 


The last half of the chapter was concerned not with how to organize your objects, but 
how to organize the geometry data used to construct these objects. By packing all the 
vertex data together in a single data structure (an array), you enable the OpenGL imple- 
mentation to make potentially valuable performance optimizations. In addition, you can 
stream the data to disk and back, thus storing the geometry in a format that is ready for 
use in OpenGL. Although OpenGL does not have a “model format” as some higher level 
APIs do, the vertex array construct is certainly a good place to start if you want to build 
your own. 


Generally, you can significantly speed up static geometry by using display lists, and you 
can use vertex arrays whenever you want dynamic geometry. Index vertex arrays, on the 
other hand, can potentially (but not always) give you the best of both worlds—flexible 
geometry data and highly efficient memory transfer and geometric processing. For many 
applications, vertex arrays are used almost exclusively. However, the old g1Begin/glEnd 
construct still has many uses, besides allowing you to create display lists—any time the 
amount of geometry fluctuates dynamically from frame to frame, for example. There is 
little benefit to continually rebuilding a vertex array from scratch rather than letting the 
driver do the work with g1Begin/glEnd. 


Reference 


glArrayElement 


Purpose: Specifies an array element used to render a vertex. 
Include File: <gl.h> 


Reference 


Syntax: 
void glArrayElement(GLint index) ; 


Description: You use this function with a g1Begin/glEnd pair to specify vertex data. 
The indexed element from any enabled vertex arrays are passed to 
OpenGL as part of the primitive definition. 


Parameters: 

index GLint: The index of the array element to use. 

Returns: None. 

See Also: glDrawArrays, glDrawElements, glDrawRangeElements, 
glInterleavedArrays 

glCallList 

Purpose: Executes a display list. 

Include File: <gl.h> 

Syntax: 


void glCallList(GLuint list); 


Description: This function executes the display list identified by list. The OpenGL 
state machine is not restored after this function is called, so it is a good 
idea to call glPushMatrix beforehand and glPopMatrix afterward. Calls to 
glCallList can be nested. The glGet function with the 
GL_MAX_LIST_NESTING argument returns the maximum number of allow- 
able nests. For Microsoft Windows, this value is 64. 


Parameters: 

list GLuint: Identifies the display list to be executed. 
Returns: None. 

See Also: glCallLists, glDeleteLists, glGenLists, glNewList 
glCallLists 

Purpose: Executes a list of display lists. 


Include File: <gl.h> 
Syntax: 
void glCallLists(GLsizei n, GLenum type, const GLvoid *lists); 
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Description: This function calls the display lists listed in the *lists array sequentially. 
This array can be of nearly any data type. The result is converted or 
clamped to the nearest integer value to determine the actual index of the 
display list. Optionally, the list values can be offset by a value specified 
by the glListBase function. 

Parameters: 

n GLsizei: The number of elements in the array of display lists. 

type GLenum: The data type of the array stored at *lists. It can be any one of 
the following values: GL_BYTE, GL_UNSIGNED_BYTE, GL_SHORT, 
GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT, GL_2_BYTES, 
GL_3_BYTES, and GL_4_BYTES. 

*lists GLvoid: An array of elements of the type specified in type. The data type 
is void to allow any of the preceding data types to be used. 

Returns: None. 

See Also: glCallList, glDeleteLists, glGenLists, glListBase, glNewList 

glColorPointer 

Purpose: Defines an array of color data for OpenGL vertex array functionality. 


Include File: 
Syntax: 


<gl.h> 


void glColorPointer(GLint size, GLenum type, GLsizei stride, const GLvoid *pointer) ; 


Description: 


Parameters: 
size 


type 


stride 


pointer 


This function defines the location, organization, and type of data to be 
used for vertex color data when OpenGL is using the vertex array func- 
tions. The buffer pointed to by this function can contain dynamic data 
but must remain valid data. The data is read afresh from the vertex array 
buffer supplied here whenever OpenGL evaluates vertex arrays. 


GLint: The number of components per color. Valid values are 3 and 4. 


GLenum: The data type of the array. It can be any of the valid OpenGL 
data types for color component data: GL_BYTE, GL_UNSIGNED_BYTE, 
GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT, and 
GL_DOUBLE. 


GLsizei: The byte offset between colors in the array. A value of 0 indi- 
cates that the data is tightly packed. 


GLvoid*: A pointer that specifies the location of the beginning of the 
vertex array data. 


Reference 
Returns: None. 
See Also: glVertexPointer, glNormalPointer, glTexCoordPointer, 
glEdgeFlagPointer, glFogCoordPointer, glinterleavedArrays 
glDeleteLists 
Purpose: Deletes a continuous range of display lists. 
Include File: <gl.h> 
Syntax: 
void glDeleteLists(GLuint list, GLsizei range); 
Description: This function deletes a range of display lists. The range goes from an 


initial value and proceeds until the number of lists deleted as specified by 
range is completed. Deleting unused display lists can save considerable 
memory. Unused display lists in the range of those specified are ignored 
and do not cause an error. 


Parameters: 

list GLuint: The integer name of the first display list to delete. 

range GLsizei: The number of display lists to be deleted following the initially 
specified list. 

Returns: None. 

See Also: glCallList, glCallLists, glGenLists, glIsList, glNewList 

glDrawArrays 

Purpose: Creates a sequence of primitives from any enabled vertex arrays. 

Include File: <gl.h> 

Syntax: 


void glDrawArrays(GLenum mode, GLint first, GLsizei count); 


Description: This function enables you to render a series of primitives using the data 
in the currently enabled vertex arrays. The function takes the primitive 
type and processes all the vertices within the specified range. 

Parameters: 

mode GLenum: The kind of primitive to render. It can be any of the valid 
OpenGL primitive types: GL_POINTS, GL_LINES, GL_LINE_LOOP, 
GL_LINE_STRIP, GL_TRIANGLES, GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN, 
GL_QUADS, GL_QUAD_STRIP, and GL_POLYGON. 
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first GLint: The first index of the enabled arrays to use. 

count GLsizei: The number of indices to use. 

Returns: None. 

See Also: glDrawElements, glDrawRangeElements, glInterleavedArrays 
glDrawElements 

Purpose: Renders primitives from array data, using an index into the array. 


Include File: <gl.h> 
Syntax: 
void glDrawElements(GLenum mode, GLsizei count, GLenum type, GLvoid *pointer) ; 


Description: Rather than traverse the array data sequentially, this function traverses an 
index array sequentially. This index array typically accesses the vertex 
data in a nonsequential and often repetitious way, allowing for shared 
vertex data. 


Parameters: 


mode GLenum: The primitive type to be rendered. It can be GL_POINTS, GL_LINES, 
GL_LINE_LOOP, GL_LINE_STRIP, GL_TRIANGLES, GL_TRIANGLE_FAN, 
GL_TRIANGLE_STRIP, GL_QUAD, GL_QUAD_STRIP, or GL_POLYGON. 


count GLsizei: The byte offset between coordinates in the array. A value of 0 
indicates that the data is tightly packed. 


type GLenum: The type of data used in the index array. It can be any one of 
GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT, or GL_UNSIGNED_INT. 

pointer GLvoid*: A pointer that specifies the location of the index array. 

Returns: None. 

See Also: glArrayElement, glDrawArrays, glDrawRangeElements, 


glDrawMultiRangeElements 


glDrawRangeElements 

Purpose: Renders primitives from array data, using an index into the array and a 
specified range of valid index values. 

Include File: <gl.h> 

Syntax: 


void glDrawRangeElements(GLenum mode, GLuint start, GLuint end, 
GLsizei count, GLenum type, GLvoid *pointer); 


Reference 


Description: Rather than traverse the array data sequentially, this function traverses an 
index array sequentially. This index array typically accesses the vertex 
data in a nonsequential and often repetitious way, allowing for shared 
vertex data. In addition to this shared functionality with g1DrawElements, 
this function takes a range of valid index values. Some OpenGL imple- 
mentations can use this information to prefetch the vertex data for 
higher performance. 

Parameters: 

mode GLenum: The primitive type to be rendered. It can be GL_POINTS, GL_LINES, 
GL_LINE_LOOP, GL_LINE_STRIP, GL_TRIANGLES, GL_TRIANGLE_FAN, 
GL_TRIANGLE_STRIP, GL_QUAD, GL_QUAD_STRIP, or GL_POLYGON. 

start GLint: The first index of the index range that will be used. 

end GLint: The last index of the index range that will be used. 

count GLsizei: The byte offset between coordinates in the array. A value of 0 
indicates that the data is tightly packed. 

type GLenum: The type of data used in the index array. It can be any one of 
GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT, or GL_UNSIGNED_INT. 

pointer GLvoid*: A pointer that specifies the location of the index array. 

Returns: None. 

See Also: glArrayElement, glDrawArrays, glDrawElements, 
glDrawMultiRangeElements 

glEdgeFlagPointer 

Purpose: Defines an array of edge flags for OpenGL vertex array functionality. 


Include File: 
Syntax: 


<gl.h> 


void glEdgeFlagPointer(GLsizei stride, const GLvoid *pointer); 


Description: 


This function defines the location of data to be used for the edge flag 
array when OpenGL is using the vertex array functions. The buffer 
pointed to by this function can contain dynamic data but must remain 
valid data. The data is read afresh from the vertex array buffer supplied 
here whenever OpenGL evaluates vertex arrays. Note that there is no 
type argument as in the other vertex array pointer functions. The data 
type for edge flags must be GLboolean. 
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Parameters: 

stride GLsizei: The byte offset between edge flags in the array. A value of 0 
indicates that the data is tightly packed. 

pointer GLvoid*: A pointer that specifies the location of the beginning of the 
vertex array data. 

Returns: None. 

See Also: glColorPointer, glNormalPointer, glTexCoordPointer, 


glVertexPointer, glFogCoordPointer, glEdgeFlagPointer, 
glSecondaryColorPointer 


glEnableClientState/glDisableClientState 
Purpose: Specify the array type to enable or disable for use with OpenGL vertex 


arrays. 
Include File: <gl.h> 
Syntax: 


void glEnableClientState(GLenum array) ; 
void glDisableClientState(GLenum array) ; 


Description: These functions tell OpenGL that you will or will not be specifying vertex 
arrays for geometry definitions. Each array type can be enabled or 
disabled individually. The use of vertex arrays does not preclude use of 
the normal glVertex family of functions. The specification of vertex 
arrays cannot be stored in a display list. 


Parameters: 

array GLenum: The name of the array to enable or disable. Valid values are 
GL_VERTEX_ARRAY, GL_COLOR_ARRAY, GL_SECONDARY_COLOR_ARRAY, 
GL_NORMAL_ARRAY, GL_FOG_COORDINATE_ARRAY, GL_TEXTURE_COORD_ARRAY, 
and GL_EDGE_FLAG_ARRAY. 

Returns: None. 

See Also: glVertexPointer, glNormalPointer, glTexCoordPointer, 
glColorPointer, glEdgeFlagPointer, glSecondaryColorPointer, 
glFogCoordPointer 

glEndList 

Purpose: Delimits the end of a display list. 

Include File: <gl.h> 

Syntax: 


void glEndList( void); 


Reference 


Description: Display lists are created by first calling g1NewList. Thereafter, all OpenGL 
commands are compiled and placed in the display list. The glEndList 
function terminates the creation of this display list. 

Returns: None. 

See Also: glCallList, glCallLists, glDeleteLists, glGenLists, glIsList 

glFogCoordPointer 

Purpose: Defines an array of fog coordinates for OpenGL vertex array function- 


Include File: 
Syntax: 


ality. 
<gl.h> 


void glFogCoordPointer(GLenum type, GLsizei stride, const GLvoid *pointer); 


Description: 


Parameters: 


type 


stride 
pointer 


Returns: 
See Also: 


glGenLists 


Purpose: 
Include File: 
Syntax: 


This function defines the location, organization, and type of data to be 
used for fog coordinates when OpenGL is using the vertex array func- 
tions. The buffer pointed to by this function can contain dynamic data 
but must remain valid data. The data is read afresh from the vertex array 
buffer supplied here whenever OpenGL evaluates vertex arrays. 


GLenum: The data type of the array. It can be any of the valid OpenGL 
data types for color component data: GL_BYTE, GL_UNSIGNED_BYTE, 
GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT, and 
GL_DOUBLE. 


GLsizei: The byte offset between colors in the array. A value of 0 indi- 
cates that the data is tightly packed. 


GLvoid*: A pointer that specifies the location of the beginning of the 
vertex array data. 


None. 


glColorPointer, glSecondaryColorPointer, glNormalPointer, 
glTexCoordpointer, glEdgeFlagPointer 


Generates a continuous range of empty display lists. 
<gl.h> 


GLuint glGenLists(GLsizei range); 
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Description: This function creates a range of empty display lists. The number of lists 
generated depends on the value specified in range. The return value is 
then the first display list in this range of empty display lists. The purpose 
of this function is to reserve a range of display list values for future use. 

Parameters: 

range GLsizei: The number of empty display lists requested. 

Returns: The first display list of the range requested. The display list values follow- 
ing the return value up to range -1 are created empty. 

See Also: glCallList, glCallLists, glDeleteLists, glNewList 

glinterleavedArrays 

Purpose: Enables and disables multiple vertex arrays simultaneously and specifies 


Include File: 
Syntax: 


an address that points to all the vertex data contained in one aggregate 
array. 


<gl.h> 


void glInterleavedArrays(GLenum format, GLsizei stride, GLvoid *pointer) ; 


Description: 


Parameters: 


format 
stride 


pointer 
Returns: 


Similar to the g1XxxPointer functions, this function enables and disables 
several vertex arrays simultaneously. All the enabled arrays are inter- 
leaved together in one aggregate array. This functionality could be 
achieved by careful use of the stride parameter in the other vertex array 
functions, but this function saves several steps and can be optimized by 
the OpenGL implementation. 


GLenum: The packing format of the vertex data in the interleaved array. It 
can be any one of the values shown in Table 11.3. 


GLsizei: The byte offset between coordinates in the array. A value of 0 
indicates that the data is tightly packed. 


GLvoid*: A pointer that specifies the location of the interleaved array. 
None. 


TABLE 11.3 Supported Interleaved Vertex Array Formats 


Format 
GL_V2F 


GL_V3F 
GL_C4UB_V2F 


Details 


Two GL_FLOAT values for the vertex data. 

Three GL_FLOAT values for the vertex data. 

Four GL_UNSIGNED_BYTE values for color data and two GL_FLOAT values for 
the vertex data. 


Reference 


en I eS eS eee 

GL_C4uB_V3F Four GL_UNSIGNED_BYTE values for color data and three GL_FLOAT values for 
vertex data. 

GL_C3F_V3F Three GL_FLOAT values for color data and three GL_FLOAT values for vertex 
data. 

GL_NSF_V3F Three GL_FLOAT values for normal data and three GL_FLOAT values for vertex 
data. 

GL_C4F_N3F_V3F Four GL_FLOAT values for color data, three GL_FLOAT values for normal data, 
and three GL_FLOAT values for vertex data. 

GL_T2F_V3F Two GL_FLOAT values for texture coordinates, three GL_FLOAT values for 
vertex data. 

GL_T4F_v4F Four GL_FLOAT values for texture coordinates and four GL_FLOAT values for 
vertex data. 

GL_T2F_C4UB_V3F Two GL_FLOAT values for texture coordinates, four GL_UNSIGNED_BYTE values 
for color data, and three GL_FLOAT values for vertex data. 

GL_T2F_C3F_V3F Two GL_FLOAT values for texture data, three GL_FLOAT values for color data, 
and three GL_FLOAT values for vertex data. 

GL_T2F_N3F_V3F Two GL_FLOAT values for texture coordinates, three GL_FLOAT values for 
normals, and three GL_FLOAT values for vertex data. 

GL_T2F_C4F_N3F_V3F Two GL_FLOAT values for texture coordinates, four GL_FLOAT values for color 
data, three GL_FLOAT values for normals, and three GL_FLOAT values for 
vertex data. 

GL_T4F_C4F_N3F_V4F Four GL_FLOAT values for texture coordinates, four GL_FLOAT values for 


colors, three GL_FLOAT values for normals, and four GL_FLOAT for vertex data. 


See Also: glColorPointer, glEdgeFlagPointer, glSecondaryColorPointer, 
glFogCoordPointer, glNormalPointer, glTexCoordPointer, 
glVertexPointer 

glisList 

eae an i IS ES SR eee eee 

Purpose: Tests for the existence of a display list. 


Include File: <gl.h> 
Syntax: 
GLboolean glIsList(GLuint list); 


Description: This function enables you to find out whether a display list exists for a 
given identifier. You can use this function to test display list values before 
using them. 
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Parameters: 
list 


Returns: 
See Also: 


glListBase 


Purpose: 


Include File: 
Syntax: 


It’s All About the Pipeline: Faster Geometry Throughput 


GLuint: The value of a potential display list. This function tests this value 
to see whether a display list is defined for it. 


GL_TRUE if the display list exists; otherwise, GL_FALSE. 
glCallList, glCallLists, glDeleteLists, glGenLists, glNewList 


Specifies an offset to be added to the list values specified in a call to 
glCallLists. 


<gl.h> 


void glListBase(GLuint base) ; 


Description: The glCallLists function calls a series of display lists listed in an array. 
This function sets an offset value that can be added to each display list 
name for this function. By default, this value is 0. You can retrieve the 
current value by calling gl1Get (GL_LIST_BASE). 

Parameters: 

base GLuint: Sets an integer offset value that will be added to display list 
names specified in calls to g1CallLists. This value is 0 by default. 

Returns: None. 

See Also: glCallLists 

glMultiDrawElements 

Purpose: Renders primitives from multiple arrays of data, using an array of indices 


Include File: 
Syntax: 


into the arrays. 
<gl.h> 


void glMultiDrawElements(GLenum mode, GLsizei *count, GLenum type, 


Description: 


GLvoid **indices, GLsizei primcount) ; 


This function has the effect of multiple calls to g1DrawElements. For each 
set of primitives, an array is passed in the count parameter that specifies 
the number of array elements for each primitive batch. The indices 
array contains an array of arrays; each array is the corresponding element 
array for each primitive batch. 


Reference 


Parameters: 

mode GLenum: The primitive type to be rendered. It can be GL_POINTS, GL_LINES, 
GL_LINE_LOOP, GL_LINE_STRIP, GL_TRIANGLES, GL_TRIANGLE_FAN, 
GL_TRIANGLE_STRIP, GL_QUAD, GL_QUAD STRIP, or GL_POLYGON. 

count GLsizei*: An array of the number of vertices contained in each array of 
elements. 

type GLenum: The type of data used in the index array. It can be any one of 
GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT, or GL_UNSIGNED_INT. 

indices GLvoid**: An array of pointers to lists of array elements. 

primcount GLsizei: The number of arrays of elements contained by the count and 
indices arrays. 

Returns: None. 

See Also: glDrawElements, glDrawRangeElements 

glINewList 

Purpose: Begins the creation or replacement of a display list. 


Include File: 
Syntax: 


<gl.h> 


void glNewList(GLuint list, GLenum mode); 


Description: 


A display list is a group of OpenGL commands that are stored for execu- 
tion on command. You can use display lists to speed up drawings that are 
computationally intensive or that require data to be read from a disk. The 
glNewList function begins a display list with an identifier specified by 
the integer list parameter. The display list identifier is used by 
glCallList and glCallLists to refer to the display list. If it’s not unique, 
a previous display list may be overwritten. You can use glGenLists to 
reserve a range of display list names and glIsList to test a display list 
identifier before using it. Display lists can be compiled only or compiled 
and executed. After glNewList is called, all OpenGL commands are stored 
in the display list in the order they were issued until glEndList is called. 
The following commands are executed when called and are never stored 
in the display list itself: glIsList, glGenLists, glDeleteLists, 
glFeedbackBuffer, glSelectBuffer, glRenderMode, glReadPixels, 
glPixelStore, glFlush, glFinish, glIsEnabled, and glGet. 
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Parameters: 

list GLuint: The numerical name of the display list. If the display list already 
exists, it is replaced by the new display list. 

mode GLenum: Display lists may be compiled and executed later or compiled 
and executed simultaneously. Specify GL_COMPILE to only compile the 
display list or GL_COMPILE_AND_EXECUTE to execute the display list as it is 
being compiled. 

Returns: None. 

See Also: glCallList, glCallLists, glDeleteLists, glGenLists, glIsList 

glNorma!lPointer 

Purpose: Defines an array of normals for OpenGL vertex array functionality. 

Include File: <gl.h> 

Syntax: 


void glNormalPointer(GLenum type, GLsizei stride, const GLvoid *pointer) ; 


Description: 


Parameters: 
type 
stride 
pointer 


Returns: 


See Also: 


This function defines the location, organization, and type of data to be 
used for vertex normals when OpenGL is using the vertex array func- 
tions. The buffer pointed to by this function can contain dynamic data 
but must remain valid data. The data is read afresh from the vertex array 
buffer supplied here whenever OpenGL evaluates vertex arrays. 


GLenum: The data type of the array. It can be any of the valid OpenGL 
data types for vertex normals: GL_BYTE, GL_SHORT, GL_INT, GL_FLOAT, and 
GL_DOUBLE. 


GLsizei: The byte offset between normals in the array. A value of 0 indi- 
cates that the data is tightly packed. 


GLvoid*: A pointer that specifies the location of the beginning of the 
vertex normal array data. 


None. 


glColorPointer, glVertexPointer, glTexCoordPointer, 
glEdgeFlagPointer, glInterleavedArrays, glSecondaryColorPointer 


glSecondaryColorPointer 


Purpose: 


Include File: 


Defines an array of secondary color data for OpenGL vertex array func- 
tionality. 
<gl.h> 


Reference 


Syntax: 


void glSecondaryColorPointer(GLint size, GLenum type, GLsizei stride, 
const GLvoid *pointer); 


Description: This function defines the location, organization, and type of data to be 
used for vertex secondary color data when OpenGL is using the vertex 
array functions. The buffer pointed to by this function can contain 
dynamic data but must remain valid data. The data is read afresh from 
the vertex array buffer supplied here whenever OpenGL evaluates vertex 


arrays. 

Parameters: 

size GLint: The number of components per color. The only valid value is 3. 

type GLenum: The data type of the array. It can be any of the valid OpenGL 
data types for color component data: GL_BYTE, GL_UNSIGNED_ BYTE, 
GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT, and 
GL_DOUBLE. 

stride GLsizei: The byte offset between colors in the array. A value of 0 indi- 
cates that the data is tightly packed. 

pointer GLvoid*: A pointer that specifies the location of the beginning of the 
vertex array data. 

Returns: None. 

See Also: glColorPointer, glFogCoordPointer, glNormalPointer, 
glTexCoordPointer, glEdgeFlagPointer 

glTexCoordPointer 

Purpose: Defines an array of texture coordinates for OpenGL vertex array function- 
ality. 

Include File: <gl.h> 

Syntax: 


void glTexCoordPointer(GLint size, GLenum type, GLsizei stride, 
const GLvoid *pointer); 


Description: This function defines the location, organization, and type of data to be 
used for texture coordinates when OpenGL is using the vertex array func- 
tions. The buffer pointed to by this function can contain dynamic data 
but must remain valid data. The data is read afresh from the vertex array 
buffer supplied here whenever OpenGL evaluates vertex arrays. 
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Parameters: 

size GLint: The number of coordinates per array element. Valid values are 1, 
2, 3, and 4. 

type GLenum: The data type of the array. It can be any of the valid OpenGL 
data types for texture coordinates: GL_SHORT, GL_INT, GL_FLOAT, and 
GL_DOUBLE. 

stride GLsizei: The byte offset between coordinates in the array. A value of 0 
indicates that the data is tightly packed. 

pointer GLvoid*: A pointer that specifies the location of the beginning of the 
vertex array data. 

Returns: None. 

See Also: glColorPointer, glNormalPointer, glSecondaryColorPointer, 
glVertexPointer, glEdgeFlagPointer, glInterleavedArrays 

glVertexPointer 

Purpose: Defines an array of vertex data for OpenGL vertex array functionality. 

Include File: <gl.h> 

Syntax: 


void glVertexPointer(GLint size, GLenum type, GLsizei stride, 
const GLvoid *pointer) ; 


Description: This function defines the location, organization, and type of data to be 
used for vertex data when OpenGL is using the vertex array functions. 
The buffer pointed to by this function can contain dynamic data but 
must remain valid data. The data is read afresh from the vertex array 
buffer supplied here whenever OpenGL evaluates vertex arrays. 


Parameters: 

size GLint: The number of vertices per coordinate. Valid values are 2, 3, 
and 4. 

type GLenum: The data type of the array. It can be any of the valid OpenGL 
data types for vertex data: GL_SHORT, GL_INT, GL_FLOAT, and GL_DOUBLE. 

stride GLsizei: The byte offset between vertices in the array. A value of 0 indi- 
cates that the data is tightly packed. 

pointer GLvoid*: A pointer that specifies the location of the beginning of the 
vertex array data. 

Returns: None. 

See Also: glColorPointer, glNormalPointer, glSecondaryColorPointer, 


glTexCoordPointer, glEdgeFlagPointer, glInterleavedArrays 


CHAPTER 12 


Interactive Graphics 


by Richard S. Wright, Jr. 


WHAT YOU’LL LEARN IN THIS CHAPTER: 


How To Functions You'll Use 

Assign OpenGL selection names to primitives or groups glInitNames/g1PushName/glPopName 
of primitives 

Use selection to determine which objects are under glSelectBuffer/glRenderMode 

the mouse 

Use feedback to get information about where objects glFeedbackBuffer/gluPickMatrix 
are drawn 


Thus far, you have learned to create some sophisticated 3D graphics using OpenGL, and 
many applications do no more than generate these scenes. But many graphics applications 
(notably, games, CAD, 3D modeling, and so on) require more interaction with the scene 
itself. In addition to menus and dialog boxes, often you need to provide a way for the user 
to interact with a graphical scene. Typically, this interaction usually happens with a 
mouse. 


Selection, a powerful feature of OpenGL, allows you to take a mouse click at some position 
over a window and determine which of your objects are beneath it. The act of selecting a 
specific object on the screen is called picking. With OpenGL’s selection feature, you can 
specify a viewing volume and determine which objects fall within that viewing volume. A 
powerful utility function, gluPickMatrix, produces a matrix for you, based purely on 
screen coordinates and the pixel dimensions you specify; you use this matrix to create a 
smaller viewing volume placed beneath the mouse cursor, Then you use selection to test 
this viewing volume to see which objects are contained by it. 


Feedback allows you to get information from OpenGL about how your vertices are trans- 
formed and illuminated when they are drawn to the frame buffer. You can use this infor- 
mation to transmit rendering results over a network, send them to a plotter, or add other 
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graphics (say with GDI, for Windows programmers) to your OpenGL scene that appear to 
interact with the OpenGL objects. Feedback does not serve the same purpose as selection, 
but the mode of operation is similar and they can work productively together. You’ll see 
this teamwork later in the SELECT sample program. 


Selection 


Selection is actually a rendering mode, but in selection mode, no pixels are actually copied 
to the frame buffer. Instead, primitives that are drawn within the viewing volume (and 
thus would normally appear in the frame buffer) produce hit records in a selection buffer. 
This buffer, unlike other OpenGL buffers, is just an array of integer values. 


You must set up this selection buffer in advance and name your primitives or groups of 
primitives (your objects or models) so they can be identified in the selection buffer. You 
then parse the selection buffer to determine which objects intersected the viewing 
volume. One potential use for this capability is for visibility determination. Named objects 
that do not appear in the selection buffer fell outside the viewing volume and would not 
have been drawn in render mode. Although selection mode is fast enough for object 
picking, using it for general-purpose frustum-culling performs significantly slower than 
any of the techniques we discussed in Chapter 11, “It’s All About the Pipeline: Faster 
Geometry Throughput.” Typically, you modify the viewing volume before entering selec- 
tion mode and call your drawing code to determine which objects are in some restricted 
area of your scene. For picking, you specify a viewing volume that corresponds to the 
mouse pointer and then check which named objects are rendered beneath the mouse. 


Naming Your Primitives 


You can name every single primitive used to render your scene of objects, but doing so is 
rarely useful. More often, you name groups of primitives, thus creating names for the 
specific objects or pieces of objects in your scene. Object names, like display list names, 
are nothing more than unsigned integers. 


The names list is maintained on the name stack. After you initialize the name stack, you 
can push names on the stack or simply replace the name currently on top of the stack. 
When a hit occurs during selection, all the names currently on the name stack are 
appended to the end of the selection buffer. Thus, a single hit can return more than one 
name if needed. 


For our first example, we keep things simple. We create a simplified (and not-to-scale) 
model of the inner planets of the solar system. When the left mouse button is down, we 
display a message box describing which planet was clicked. Listing 12.1 shows some of the 
rendering code for our sample program, PLANETS. We have created macro definitions for 
the sun, Mercury, Venus, Earth, and Mars. 


Selection 


LISTING 12.1 Naming the Sun and Planets in the PLANETS Program 


FUTTTTTTTTT TTT ATT 
// Define object names 


#define 
#define 
#define 
#define 
#define 


SUN 1 
MERCURY 2 
VENUS 3 
EARTH a 
MARS 5 


FUTTTTTTTTT TTT TLL 
// Called to draw scene 
void RenderScene(void) 


{ 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 


// Save the matrix state and do the rotations 
glMatrixMode(GL_MODELVIEW) ; 
glPushMatrix(); 


// Translate the whole scene out and into view 
glTranslatef(0.0f, @.0f, -300.0f); 


// Initialize the names stack 
glInitNames(); 
glPushName(Q) ; 


// Name and draw the Sun 
glColor3f(1.0f, 1.0f, 0.0f); 
glLoadName (SUN) ; 
DrawSphere(15.Qf) ; 


// Draw Mercury 

glColor3f(0.5f, @.0f, 0.0f); 

glPushMatrix(); 
glTranslatef(24.0f, 0.0f, 0.0f); 
glLoadName (MERCURY) ; 
DrawSphere(2.0f) ; 

glPopMatrix(); 


// Draw Venus 
glColor3f(@.5f, @.5f, 1.0f); 
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LISTING 12.1 Continued 


glPushMatrix(); 
glTranslatef(60.0f, @.0f, 0.0f); 
glLoadName (VENUS) ; 
DrawSphere(4.0f) ; 

glPopMatrix(); 


// Draw the Earth 

glColor3f(0.0f, @.0f, 1.0f); 

glPushMatrix(); 
glTranslatef (100.0f ,0.0f ,0.0f) ; 
glLoadName (EARTH) ; 
DrawSphere(8.OfF) ; 

glPopMatrix(); 


// Draw Mars 

glColor3f(1.0f, 0.0f, 0.0f); 

glPushMatrix(); 
glTranslatef(150.0f, @.0f, 0.0f); 
glLoadName (MARS) ; 
DrawSphere(4.0f); 

glPopMatrix(); 


// Restore the matrix state 
glPopMatrix(); // Modelview matrix 


glutSwapBuffers(); 
} 


In PLANETS, the function initializes and clears the name stack, and glPushName pushes 0 
on the stack to put at least one entry on the stack. For the sun and each planet, we call 
glLoadName to name the object or objects about to be drawn. This name, in the form of an 
unsigned integer, is not pushed on the name stack but rather replaces the current name 
on top of the stack. Later, we discuss keeping an actual stack of names. For now, we just 
replace the top name of the name stack each time we draw an object (the sun or a particu- 
lar planet). 


Working with Selection Mode 


As mentioned previously, OpenGL can operate in three different rendering modes. The 
default mode is GL_RENDER, in which all the drawing actually occurs onscreen. To use selec- 
tion, we must change the rendering mode to selection by calling the OpenGL function: 


glRenderMode(GL_SELECTION) ; 


Selection 


When we actually want to draw again, we use the following call to place OpenGL back in 
rendering mode: 


glRenderMode (GL_RENDER) ; 


The third rendering mode is GL_FEEDBACK, discussed later in this chapter. 


The naming code in Listing 12.1 has no effect unless we first switch the rendering mode 
to selection mode. Most often, you use the same function to render the scene in both 
GL_RENDER mode and GL_SELECTION mode, as we have done here. 


Listing 12.2 provides the GLUT callback code triggered by the clicking of the left mouse 
button. This code checks for a left button click and then forwards the mouse coordinates 
to ProcessSelection, which processes the mouse click for this example. 


LISTING 12.2 Code That Responds to the Left Mouse Button Click 


FLTTITTTT TTT TTT A 
// Process the mouse click 
void MouseCallback(int button, int state, int x, int y) 
{ 
if (button == GLUT_LEFT_BUTTON && state == GLUT_DOWN) 
ProcessSelection(x, y); 


} 


The Selection Buffer 

The selection buffer is filled with hit records during the rendering process. A hit record is 
generated whenever a primitive or collection of primitives is rendered that would have 
been contained in the viewing volume. Under normal conditions, this is simply anything 
that would have appeared onscreen. 


The selection buffer is an array of unsigned integers, and each hit record occupies at least 
four elements of the array. The first array index contains the number of names that are on 
the name stack when the hit occurs. For the PLANETS example (Listing 12.1), this is 
always 1. The next two entries contain the minimum and maximum window z coordi- 
nates of all the vertices contained by the viewing volume since the last hit record. This 
value, which ranges from [0,1], is scaled to the maximum size of an unsigned integer for 
storage in the selection buffer. The fourth entry is the bottom of the name stack. If more 
than one name appears on the name stack (indicated by the first index element), they 
follow the fourth element. This pattern, illustrated in Figure 12.1, is then repeated for all 
the hit records contained in the selection buffer. We explain why this pattern can be 
useful when we discuss picking. 
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Selection buffer [0] —*— Number of names on names stack at 
time of hit = ng 
[1] —™ Minimum z value 
(2] —~ Maximum z value 
[1p+2] ~ Bottom of names stack 


Next hit record [nye] —~ Number of names on names stack for 
this record = n, 
[ng+4] Minimum z value 


FIGURE 12.1 Hit record for the selection buffer. 


The format of the selection buffer gives you no way of knowing how many hit records you 
need to parse. The selection buffer is not actually filled until you switch the rendering 
mode back to GL_RENDER. When you do this with the glRenderMode function, the return 
value is the number of hit records copied. 


Listing 12.3 shows the processing function called when a mouse click occurs for the 
PLANETS sample program. It shows the selection buffer being allocated and specified with 
glSelectBuffer. This function takes two arguments: the length of the buffer and a pointer 
to the buffer itself. 


LISTING 12.3 Function to Process the Mouse Click 


TTTTTTTLT TTT TTT TT ATTA TTL 
// Process the selection, which is triggered by a right mouse 
// click at (xPos, yPos). 
#define BUFFER_LENGTH 64 
void ProcessSelection(int xPos, int yPos) 

{ 

GLfloat fAspect; 


// Space for selection buffer 
static GLuint selectBuff[BUFFER_LENGTH] ; 


// Hit counter and viewport storage 
GLint hits, viewport[4]; 


// Setup selection buffer 
glSelectBuffer(BUFFER_LENGTH, selectBuff) ; 
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LISTING 12.3 Continued 


// Get the viewport 
glGetIntegerv(GL_VIEWPORT, viewport); 


// Switch to projection and save the matrix 
glMatrixMode(GL_PROJECTION) ; 
glPushMatrix(); 


rag | 


// Change render mode 
glRenderMode(GL_SELECT) ; 


// Establish new clipping volume to be unit cube around 

// mouse cursor point (xPos, yPos) and extending two pixels 
// in the vertical and horizontal direction 
glLoadIdentity(); 

gluPickMatrix(xPos, viewport[3] - yPos, 2,2, viewport); 


// Apply perspective matrix 
fAspect = (float)viewport[2] / (float)viewport[3]; 
gluPerspective(45.0f, fAspect, 1.0, 425.0); 


// Draw the scene 
RenderScene() ; 


// Collect the hits 
hits = glRenderMode(GL_RENDER) ; 


// If a single hit occurred, display the info. 
if(hits == 1) 
ProcessPlanet (selectBuff[3]); 


// Restore the projection matrix 
glMatrixMode(GL_PROJECTION) ; 
glPopMatrix(); 


// Go back to modelview for normal rendering 
glMatrixMode (GL_MODELVIEW) ; 
} 


Picking 


Picking occurs when you use the mouse position to create and use a modified viewing 
volume during selection. When you create a smaller viewing volume positioned in your 


618 


CHAPTER 12 Interactive Graphics 


scene under the mouse position, only objects that would be drawn within that viewing 
volume generate hit records. By examining the selection buffer, you can then see which 
objects, if any, were clicked on by the mouse. 


The gluPickMatrix function is a handy utility that creates a matrix describing the new 
viewing volume: 


void gluPickMatrix(GLdouble x, GLdouble y, GLdouble width, 
GLdouble height, GLint viewport[4]); 


The x and y parameters are the center of the desired viewing volume in OpenGL window 
coordinates. You can plug in the mouse position here, and the viewing volume will be 
centered directly underneath the mouse. The width and height parameters then specify 
the dimensions of the viewing volume in window pixels. For clicks near an object, use a 
large value; for clicks next to the object or directly on the object, use a smaller value. The 
viewport array contains the window coordinates of the currently defined viewport. You 
can easily obtain this information by calling 


glGetIntegerv(GL_VIEWPORT, viewport) ; 


Remember, as discussed in Chapter 2, “Using OpenGL,” that OpenGL window coordinates 
are the opposite of most systems’ window coordinates with respect to the way pixels are 
counted vertically. Note in Listing 12.3, we subtract the mouse y coordinate from the 
viewport’s height. This yields the proper vertical window coordinate for OpenGL: 


gluPickMatrix(xPos, viewport[3] - yPos, 2,2, viewport) ; 


To use gluPickMatrix, you should first save the current projection matrix state (thus 
saving the current viewing volume). Then call glLoadIdentity to create a unit-viewing 
volume. Calling gluPickMatrix then translates this viewing volume to the correct loca- 
tion. Finally, you must apply any further perspective projections you may have applied to 
your original scene; otherwise, you won’t get a true mapping. Here’s how it’s done for the 
PLANETS example (from Listing 12.3): 


// Switch to projection and save the matrix 
glMatrixMode (GL_PROJECTION) ; 
glPushMatrix(); 


// Change render mode 
glRenderMode(GL_SELECT) ; 


// Establish new clipping volume to be unit cube around 

// mouse cursor point (xPos, yPos) and extending two pixels 
// in the vertical and horizontal direction 
glLoadiIdentity(); 

gluPickMatrix(xPos, viewport[3] - yPos, 2,2, viewport); 


Selection 


// Apply perspective matrix 
fAspect = (float)viewport[2] / (float)viewport[3]; 
gluPerspective(45.0f, fAspect, 1.0, 425.0); 


// Draw the scene 
RenderScene() ; 


// Collect the hits 
hits = glRenderMode(GL_RENDER) ; 


In this segment, the viewing volume is saved first. Then the selection mode is entered, the 
viewing volume is modified to include only the area beneath the mouse cursor, and the 
scene is redrawn by calling RenderScene. After the scene is rendered, we call glRenderMode 
again to place OpenGL back into normal rendering mode and get a count of generated hit 
records. 


In the next segment, if a hit occurred (for this example, there is either one hit or none), 
we pass the entry in the selection buffer that contains the name of the object selected or 
our ProcessPlanet function. Finally, we restore the projection matrix (thus, the old 
viewing volume is restored) and switch the active matrix stack back to the modelview 
matrix, which is usually the default: 


// If a single hit occurred, display the info. 
if(hits == 1) 
ProcessPlanet(selectBuff[3]); 


// Restore the projection matrix 
glMatrixMode(GL_PROJECTION) ; 
glPopMatrix(); 


// Go back to modelview for normal rendering 
glMatrixMode(GL_MODELVIEW) ; 


The ProcessPlanet function simply displays a message in the windows’ caption telling 
which planet was clicked. This code is not shown because it is fairly trivial, consisting of 
no more than a switch statement and some glutSetWindowTitle function calls. 


The output from PLANETS is shown in Figure 12.2, where you can see the result of click- 
ing the second planet from the sun. 


Although we don’t go into any great detail here, it is worth discussing briefly the z values 
from the selection buffer. In the PLANETS example, each object or model was distinct and 
off alone in its own space. What if you apply this same method to several objects or 
models that perhaps overlap? You get multiple hit records! How do you know which one 
the user clicked? This situation can be tricky and requires some forethought. You can use 
the z values to determine which object was closest to the user in viewspace, which is the 
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most likely object that was clicked. Still, for some shapes and geometry, if you aren’t 
careful, it can be difficult to sort out precisely what the user intended to pick. 


FIGURE 12.2 Output from PLANETS after clicking a planet. 


Hierarchical Picking 

For the PLANETS example, we didn’t push any names on the stack, but rather just replaced 
the existing one whenever a new object was to be rendered. This single name residing on 
the name stack was the only name returned in the selection buffer. We can also get multi- 
ple names when a selection hit occurs, by placing more than one name on the name 
stack. This capability is useful, for instance, in drill-down situations when you need to 
know not only that a particular bolt was selected, but also that it belonged to a particular 
wheel, on a particular car, and so forth. 


To demonstrate multiple names being returned on the name stack, we stick with the 
astronomy theme of our previous example. Figure 12.3 shows two planets (okay, so use a 
little imagination)—a large blue planet with a single moon and a smaller red planet with 
two moons. 


Rather than just identify the planet or moon that is clicked, we want to also identify the 
planet that is associated with the particular moon. The code in Listing 12.4 shows our new 
rendering code for this scene. We push the names of the moons onto the name stack so 
that it contains the name of the planet as well as the name of the moon when selected. 


FIGURE 12.3 Two planets with their respective moons. 


LISTING 12.4 Rendering Code for the MOONS Sample Program 


TELTTTITTTT TTT ATL 
// Define object names 

#define EARTH 1 

#define MARS 2 

#define MOON1 3 

#define MOON2 4 


FUTLTTTTT TTT TTT TTT TATA A TL 
// Called to draw scene 
void RenderScene(void) 
{ 
// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH BUFFER BIT); 


// Save the matrix state and do the rotations 
glMatrixMode(GL_MODELVIEW) ; 
glPushMatrix(); 


// Translate the whole scene out and into view 
glTranslatef(0.0f, 0.0f, -300.0f); 


// Initialize the names stack 
glInitNames(); 
glPushName(Q) ; 


Selection 
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LISTING 12.4 Continued 


// Draw the Earth 
glPushMatrix(); 

glColor3f(0.0f, @.0f, 1.0f); 
glTranslatef(-100.0f ,0.0f ,0.O0f); 
glLoadName (EARTH) ; 
DrawSphere (30. Of) ; 


// Draw the Moon 
glTranslatef(45.0f, 0.O0f, 0.0f); 
glColor3f(®.85f, 0.85f, 0.85f); 
glPushName(MOON1) ; 
DrawSphere(5.0f) ; 

glPopName() ; 

glPopMatrix(); 


// Draw Mars 

glPushMatrix(); 

glColor3f(1.0f, @.0f, 0.0f); 
glTranslatef(100.0f, @.0f, 0.0f); 
glLoadName (MARS) ; 
DrawSphere (20. Qf) ; 


// Draw Moon 

glTranslatef(-40.0f, 40.0f, 0.0f); 
glColor3f(0.85f, 0.85f, 0.85f); 
glPushName(MOON1) ; 
DrawSphere(5.0f); 

glPopName() ; 


// Draw Moon2 

glTranslatef(0.0f, -80.0f, 0.0f); 
glPushName(MOON2) ; 
DrawSphere(5.0f) ; 

glPopName() ; 

glPopMatrix(); 


// Restore the matrix state 
glPopMatrix(); // Modelview matrix 


glutSwapBuffers() ; 
} 


Selection 


Now in our ProcessSelection function, we still call the ProcessPlanet function that we 
wrote, but this time, we pass the entire selection buffer: 


// If a single hit occurred, display the info. 
if(hits == 1) 
ProcessPlanet(selectBuff) ; 


Listing 12.5 shows the more substantial ProcessPlanet function for this example. In this 
instance, the bottom name on the name stack is always the name of the planet because it 
was pushed on first. If a moon is clicked, it is also on the name stack. This function 
displays the name of the planet selected, and if it was a moon, that information is also 
displayed. A sample output is shown in Figure 12.4. 


FIGURE 12.4 Sample output from the MOONS sample program. 


LISTING 12.5 Code That Parses the Selection Buffer for the MOONS Sample Program 


FLLTTTTTTTT TTT TTT TTT TT AL 
// Parse the selection buffer to see which 
// planet/moon was selected 
void ProcessPlanet(GLuint *pSelectBuff) 
{ 
int id,count; 
char cMessage[64]; 
strcpy(cMessage, "Error, no selection detected") ; 
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LISTING 12.5 Continued 


// How many names on the name stack 
count = pSelectBuff[Q]; 


// Bottom of the name stack 
id = pSelectBuff[3]; 


// Select on earth or mars, whichever was picked 
switch(id) 
{ 
case EARTH: 
strcpy(cMessage, "You clicked Earth."); 


// If there is another name on the name stack, 
// then it must be the moon that was selected 
// This is what was actually clicked on 
if(count == 2) 
strcat(cMessage," - Specifically the moon."); 


break; 


case MARS: 
strcepy(cMessage, "You clicked Mars."); 


// We know the name stack is only two deep. The precise 
// moon that was selected will be here. 
if(count == 2) 


{ 
if (pSelectBuff[4] == MOON1) 
strcat(cMessage," - Specifically Moon #1."); 
else 
strcat(cMessage," - Specifically Moon #2."); 
} 
break; 


// Display the message about planet and moon selection 
glutSetWindowTitle(cMessage) ; 
} 


Selection 


Feedback 


Feedback, like selection, is a rendering mode that does not produce output in the form of 
pixels on the screen. Instead, information is written to a feedback buffer indicating how 
the scene would have been rendered. This information includes transformed vertex data in 
window coordinates, color data resulting from lighting calculations, and texture data— 
essentially everything needed to rasterize the primitives. 


You enter feedback mode the same way you enter selection mode, by calling glRenderMode 
with a GL_FEEDBACK argument. You must reset the rendering mode to GL_RENDER to fill the 
feedback buffer and return to normal rendering mode. 


The Feedback Buffer 


The feedback buffer is an array of floating-point values specified with the glFeedback 
function: 


void glFeedbackBuffer(GLsizei size, GLenum type, GLfloat *buffer); 
This function takes the size of the feedback buffer, the type and amount of drawing infor- 
mation wanted, and a pointer to the buffer itself. 


Valid values for type appear in Table 12.1. The type of data specifies how much data is 
placed in the feedback buffer for each vertex. Color data is represented by a single value in 
color index mode or four values for RGBA color mode. 


TABLE 12.1 Feedback Buffer Types 


Color Data Vertex Texture Data Total Values Type Coordinates 
GL_2D xy N/A N/A 2 

GL_3D x, y, Z N/A N/A 3 
GL_3D_COLOR XYZ [a N/A 3+C 
GL_3D_COLOR_TEXTURE XP ¥z Cc 4 7+ 
GL_4D_COLOR_TEXTURE x, y, Z, W (& 4 8+C 


Feedback Data 


The feedback buffer contains a list of tokens followed by vertex data and possibly color 
and texture data. You can parse for these tokens (see Table 12.2) to determine the types of 
primitives that would have been rendered. One limitation of feedback occurs when using 
multiple texture units. In this case, only texture coordinates from the first texture unit are 
returned. 
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TABLE 12.2 Feedback Buffer Tokens 


Token Primitive 

GL_POINT_TOKEN Points 

GL_LINE_TOKEN Line 

GL_LINE_RESET_TOKEN Line segment when line stipple is reset 
GL_POLYGON_TOKEN Polygon 

GL_BITMAP_TOKEN Bitmap 

GL_DRAW_PIXEL_TOKEN Pixel rectangle drawn 
GL_COPY_PIXEL_TOKEN Pixel rectangle copied 
GL_PASS_THROUGH_TOKEN User-defined marker 


The point, bitmap, and pixel tokens are followed by data for a single vertex and possibly 
color and texture data. This depends on the data type from Table 12.1 specified in the call 
to glFeedbackBuffer. The line tokens return two sets of vertex data, and the polygon 
token is immediately followed by the number of vertices that follow. The user-defined 
marker (GL_PASS_THROUGH_TOKEN) is followed by a single floating-point value that is user 
defined. Figure 12.5 shows an example of a feedback buffer’s memory layout if a GL_3D 
type were specified. Here, we see the data for a point, token, and polygon rendered in that 
order. 


Feedback buffer [0] — GL_POINT_TOKEN 
(1] — x coordinate 
[2] — y coordinate 
[3] — x coordinate 
[4] — GL_PASS_THROUGH_TOKEN 
[5] — User-defined value 
[6] — GL_POLYGON_TOKEN 
[7] — Number of vertices 
[8] — x coordinate of first vertex 
[9] — y coordinate of first vertex 
[10]— z coordinate of first vertex 
{11]— x coordinate of second vertex 


[n] z coordinate of last vertex 


FIGURE 12.5 A sample memory layout for a feedback buffer. 


A Feedback Example 


Passthrough Markers 

When your rendering code is executing, the feedback buffer is filled with tokens and 
vertex data as each primitive is specified. Just as you can in selection mode, you can flag 
certain primitives by naming them. In feedback mode, you can set markers between your 
primitives, as well. You do so by calling glPassThrough: 


void glPassThrough(GLfloat token); 


This function places a GL_PASS_THROUGH_TOKEN in the feedback buffer, followed by the 
value you specify when calling the function. This process is somewhat similar to naming 
primitives in selection mode. It’s the only way of labeling objects in the feedback buffer. 


A Feedback Example 


An excellent use of feedback is to obtain window coordinate information regarding any 
objects that you render. You can then use this information to place controls or labels near 
the objects in the window or other windows around them. 


To demonstrate feedback, we use selection to determine which of two objects on the 
screen has been clicked by the user. Then we enter feedback mode and render the scene 
again to obtain the vertex information in window coordinates. Using this data, we deter- 
mine the minimum and maximum x and y values for the object and use those values to 
draw a focus rectangle around the object. The result is graphical selection and deselection 
of one or both objects. 


Label the Objects for Feedback 

Listing 12.6 shows the rendering code for our sample program, SELECT. Don’t confuse this 
example with a demonstration of selection mode! Even though selection mode is 
employed in our example to select an object on the screen, we are demonstrating the 
process of getting enough information about that object—using feedback—to draw a 
rectangle around it using normal Windows coordinates GDI commands. Notice the use of 
glPassThrough to label the objects in the feedback buffer, right after the calls to 
glLoadName to label the objects in the selection buffer. Because these functions are ignored 
when the render mode is GL_RENDER, they have an effect only when rendering for selection 
or feedback. 


LISTING 12.6 Rendering Code for the SELECT Sample Program 


FTTTTTTT TTT AAA 
// Object Names 

#define TORUS 1 

#define SPHERE 2 
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LISTING 12.6 Continued 


FLELTTTTTT LTT TTT TT 


// Render the torus and sphere 
void DrawO0bjects(void) 


} 


FUTTTTLTTTATT TTT TTT TAT TTT TT TT 


{ 


// Save the matrix state and do the rotations 


glMatrixMode(GL_MODELVIEW) ; 
glPushMatrix(); 


// Translate the whole scene out and into view 
glTranslatef(-0.75f, 0.0f, -2.5f); 


// Initialize the names stack 
glInitNames() ; 
glPushName(Q) ; 


// Set material color, Yellow 
// torus 

glColor3f(1.0f, 1.0f, 0.0f); 
glLoadName (TORUS) ; 
glPassThrough( (GLfloat) TORUS) ; 
DrawTorus(40, 20); 


// Draw Sphere 

glColor3f(0.5f, @.0f, 0.0f); 
glTranslatef(1.5f, @.0f, 0.0f); 
glLoadName (SPHERE) ; 
glPassThrough( (GLfloat) SPHERE) ; 
DrawSphere(@.5f); 


// Restore the matrix state 


glPopMatrix(); // Modelview matrix 


// Called to draw scene 
void RenderScene(void) 


{ 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 


A Feedback Example 


LISTING 12.6 Continued 


// Draw the objects in the scene 
DrawObjects(); 


// If something is selected, draw a bounding box around it 
if(selectedObject != 0) 
{ 


int viewport[4]; 


// Get the viewport 
glGetIntegerv(GL_VIEWPORT, viewport); 


// Remap the viewing volume to match window coordinates (approximately) 
glMatrixMode(GL_PROJECTION) ; 

glPushMatrix(); 

glLoadIdentity(); 


// Establish clipping volume (left, right, bottom, top, near, far) 
glOrtho(viewport[®], viewport[2], viewport[3], viewport[1], -1, 1); 
glMatrixMode(GL_MODELVIEW) ; 


glDisable(GL_LIGHTING) ; 

glColor3f(1.0f, @.0f, 0.0f); 

glBegin(GL_LINE LOOP) ; 
glVertex2i(boundingRect.left, boundingRect.top) ; 
glVertex2i(boundingRect.left, boundingRect.bottom) ; 
glVertex2i(boundingRect.right, boundingRect.bottom) ; 
glVertex2i(boundingRect.right, boundingRect.top) ; 

glEnd(); 

glEnable(GL_LIGHTING) ; 

} 


glMatrixMode(GL_PROJECTION) ; 
glPopMatrix(); 
glMatrixMode (GL_MODELVIEW) ; 


glutSwapBuffers(); 
} 


For this example, the rendering code is broken into two functions: RenderScene and 
DrawObjects. RenderScene is our normal top-level rendering function, but we have moved 
the actual drawing of the objects that we may select to outside this function. The 
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RenderScene function draws the objects, but it also draws the bounding rectangle around 
an object if it is selected. selectedObject is a variable we will use in a moment to indicate 
which object is currently selected. 


Step 1: Select the Object 


Figure 12.6 shows the output from this rendering code, displaying a torus and sphere. 
When the user clicks one of the objects, the function ProcessSelection is called (see 
Listing 12.7). This is similar to the selection code in the previous two examples (in Listings 
12.3 and 12.5). 


FIGURE 12.6 Output from the SELECT program after the sphere has been clicked. 


LISTING 12.7 Selection Processing for the SELECT Sample Program 


TULTTTTTTTT TTT TTT TTT LTT TTL 
// Process the selection, which is triggered by a right mouse 
// click at (xPos, yPos). 
#define BUFFER_LENGTH 64 
void ProcessSelection(int xPos, int yPos) 

{ 

// Space for selection buffer 

static GLuint selectBuff[BUFFER_LENGTH] ; 


A Feedback Example 


LISTING 12.7 Continued 


// Hit counter and viewport storage 
GLint hits, viewport[4]; 


// Setup selection buffer 
glSelectBuffer(BUFFER_LENGTH, selectBuff) ; 


// Get the viewport 
glGetIntegerv(GL_VIEWPORT, viewport); 


// Switch to projection and save the matrix 
glMatrixMode(GL_PROJECTION) ; 
glPushMatrix(); 


// Change render mode 
glRenderMode(GL_SELECT) ; 


// Establish new clipping volume to be unit cube around 

// mouse cursor point (xPos, yPos) and extending two pixels 
// in the vertical and horizontal direction 
glLoadIdentity(); 

gluPickMatrix(xPos, viewport[3] - yPos, 2,2, viewport); 


// Apply perspective matrix 
gluPerspective(60.0f, fAspect, 1.0, 425.0); 


// Draw the scene 
DrawObjects(); 


// Collect the hits 
hits = glRenderMode(GL_RENDER) ; 


// Restore the projection matrix 
glMatrixMode(GL_PROJECTION) ; 
glPopMatrix(); 


// Go back to modelview for normal rendering 
glMatrixMode(GL_MODELVIEW) ; 


// If a single hit occurred, display the info. 
if(hits == 1) 

{ 

MakeSelection(selectBuff[3]); 
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LISTING 12.7. Continued 


if(selectedObject == selectBuff[3] ) 
selectedObject = 0; 

else 
selectedObject = selectBuff[3]; 


glutPostRedisplay(); 
} 


Step 2: Get Feedback on the Object 

Now that we have determined which object was clicked (we saved this in the 
selectedObject variable), we set up the feedback buffer and render again in feedback 
mode. Listing 12.8 shows the code that sets up feedback mode for this example and calls 
DrawObjects to redraw just the torus and sphere scene. This time, however, the 
glPassThrough functions put markers for the objects in the feedback buffer. 


LISTING 12.8 Load and Parse the Feedback Buffer 


FLTLTTTT TTT LTT TTT TTT TT TL 
// Go into feedback mode and draw a rectangle around the object 
#define FEED_BUFF_SIZE 32768 
void MakeSelection(int nChoice) 
{ 
// Space for the feedback buffer 
static GLfloat feedBackBuff [FEED _BUFF_SIZE]; 


// Storage for counters, etc. 
int size,i,j,count; 


// Initial minimum and maximum values 
boundingRect.right = boundingRect.bottom = -999999.0f; 
boundingRect.left = boundingRect.top = 999999.0f; 


// Set the feedback buffer 
glFeedbackBuffer(FEED_BUFF_SIZE,GL_2D, feedBackBuff) ; 


// Enter feedback mode 
glRenderMode (GL_FEEDBACK) ; 


// Redraw the scene 
DrawObjects(); 


A Feedback Example 


LISTING 12.8 Continued 


// Leave feedback mode 
size = glRenderMode(GL_RENDER) ; 


// Parse the feedback buffer and get the 
// min and max X and Y window coordinates 


i=0; 
while(i < size) 
{ 


// Search for appropriate token 
if (feedBackBuff[i] == GL_PASS_THROUGH_TOKEN) 
if (feedBackBuff[i+1] == (GLfloat)nChoice) 
{ 
it= 2; 
// Loop until next token is reached 
while(i < size && feedBackBuff[i] != GL_PASS_THROUGH_TOKEN) 
{ 
// Just get the polygons 
if (feedBackBuff[i] == GL_POLYGON_TOKEN) 
{ 
// Get all the values for this polygon 
count = (int)feedBackBuff[++i]; // How many vertices 
ins 
for(j = 0; j < count; j++) // Loop for each vertex 
{ 
// Min and Max X 
if (feedBackBuff[i] > boundingRect.right) 
boundingRect.right = feedBackBuff[i]; 


if (feedBackBuff[i] < boundingRect. left) 
boundingRect.left = feedBackBuff [i]; 

Leh: 

// Min and Max Y 

if (feedBackBuff[i] > boundingRect.bottom) 
boundingRect.bottom = feedBackBuff[i]; 


if (feedBackBuff[i] < boundingRect.top) 
boundingRect.top = feedBackBuff [i]; 
i++ 


} 


633 


ral 


634 CHAPTER 12 Interactive Graphics 


LISTING 12.8 Continued 


} 
else 
itt; // Get next index and keep looking 
} 
break; 
} 
it+s 
} 


When the feedback buffer is filled, we search it for GL_PASS_THROUGH_TOKEN. When we find 
one, we get the next value and determine whether it is the one we are looking for. If so, 
the only task that remains is to loop through all the polygons for this object and get the 
minimum and maximum window x and y values. These values are stored in the 
boundingRect structure and then used by the RenderScene function to draw a focus 
rectangle around the selected object. 


Summary 


Selection and feedback are two powerful features of OpenGL that enable you to facilitate 
the user’s active interaction with a scene. Selection and picking are used to identify an 
object or region of a scene in OpenGL coordinates rather than just window coordinates. 
Feedback returns valuable information about how an object or primitive is actually drawn 
in the window. You can use this information to implement features such as annotations or 
bounding boxes in your scene. 


Reference 


glFeedbackBuffer 


Purpose: Sets the buffer to be used for feedback data. 

Include File: <gl.h> 

Syntax: 

void glFeedbackBuffer(GLsizei size, GLenum type, GLfloat *buffer); 


Description: This function establishes the feedback buffer and type of vertex informa- 
tion desired. Feedback is a rendering mode; rather than render to the 
frame buffer, OpenGL sends vertex data to the buffer specified by 
*puffer. These blocks of data can include x, y, z, and w coordinate posi- 
tions (in window coordinates); color data for color index mode or RGBA 


Parameters: 
size 


type 


buffer 
Returns: 
See Also: 


glinitNames 


Purpose: 
Include File: 
Syntax: 


Reference 


color mode; and texture coordinates. The amount and type of informa- 
tion desired are specified by the type argument. 


GLsizei: The maximum number of entries allocated for *buffer. If a 
block of data written to the feedback would overflow the amount of 
space allocated, only the part of the block that will fit in the buffer is 
written. 
GLenum: Specifies the kind of vertex data to be returned in the feedback 
buffer. Each vertex generates a block of data in the feedback buffer. For 
each of the following types, the block of data contains a primitive token 
identifier followed by the vertex data. The vertex data specifically 
includes the following: 
GL_2D: x and y coordinate pairs. 
GL_3D: x, y, and z coordinate triplets. 
GL_3D_COLOR: x, y, z coordinates and color data (one value for 
color index, four for RGBA). 
GL_3D_COLOR_TEXTURE: x, y, z coordinates; color data (one or four 
values); and four texture coordinates. If multiple texture units 
are employed, only coordinates from the first texture unit are 
returned. 
GL_4D_COLOR_TEXTURE: x, y, Z, and w coordinates; color data (one 
or four values); and four texture coordinates. 
GLfloat*: Buffer where feedback data will be stored. 
None. 


glPassThrough, glRenderMode, glSelectBuffer 


Initializes the name stack. 
<gl.h> 


void glInitNames(void ); 


Description: 


The name stack is used to allow drawing primitives or groups of primi- 
tives to be named with an unsigned integer when rendered in selection 
mode. Each time a primitive is named, its name is pushed on the name 
stack with glPushName, or the current name is replaced with glLoadName. 
This function sets the name stack to its initial condition with no names 
on the stack. 
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Returns: None. 

See Also: glInitNames, glPushName, glRenderMode, glSelectBuffer 
glLoadName 

Purpose: Loads a name onto the name stack. 

Include File: <gl.h> 

Syntax: 


void glLoadName(GLuint name) ; 


Description: This function places the name specified in the top entry of the name 
stack. The name stack is used to name primitives or groups of primitives 
when rendered in selection mode. The current name on the name stack is 
actually replaced by the name specified with this function. 


Parameters: 

name GLuint: Specifies the name to be placed on the name stack. Selection 
names are unsigned integers. 

Returns: None. 

See Also: glInitNames, glPushName, glRenderMode, glSelectBuffer 

glPassThrough 

Purpose: Places a marker in the feedback buffer. 

Include File: <gl.h> 

Syntax: 


void glPassThrough(GLfloat token) ; 


Description: When OpenGL is placed in feedback mode, no pixels are drawn to the 
frame buffer. Instead, information about the drawing primitives is placed 
in a feedback buffer. This function allows you to place the token 
GL_PASS_THROUGH_TOKEN in the midst of the feedback buffer data, which is 
followed by the floating-point value specified by token. This function is 
called in your rendering code and has no effect unless in feedback mode. 


Parameters: 

token GLfloat: A value to be placed in the feedback buffer following the 
GL_PASS_THROUGH_TOKEN. 

Returns: None. 


See Also: glFeedbackBuffer, glRenderMode 


Reference 


glPopName 

Purpose: Pops (removes) the top entry from the name stack. 
Include File: <gl.h> 

Syntax: 


void glPopName(void) ; 


Description: The name stack is used during selection to identify drawing commands. 
This function removes a name from the top of the name stack. The 
current depth of the name stack can be retrieved by calling glGet with 
GL_NAME_STACK_DEPTH. Popping off an empty name stack generates an 
OpenGL error (see glGetError). 


Returns: None. 

See Also: glInitNames, glLoadName, glRenderMode, glSelectBuffer, glPushName 
glPushName 

Purpose: Specifies a name that will be pushed on the name stack. 

Include File: <gl.h> 

Syntax: 


void glPushName(GLuint name) ; 


Description: The name stack is used during selection to identify drawing commands. 
This function pushes a name on the name stack to identify any subse- 
quent drawing commands. The name stack’s maximum depth can be 
retrieved by calling glGet with GL_MAX_NAME_STACK_DEPTH and the current 
depth by calling glGet with GL_NAME_STACK_DEPTH. The maximum depth 
of the name stack can vary with implementation, but all implementa- 
tions must support at least 64 entries. Pushing past the end of the name 
stack generates an OpenGL error and will most likely be ignored by the 


implementation. 
Parameters: 
name GLuint: The name to be pushed onto the name stack. 
Returns: None. 
See Also: glInitNames, glLoadName, glRenderMode, glSelectBuffer, glPopName 
glRenderMode 
Purpose: Sets one of three rasterization modes. 


Include File: <gl.h> 
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Syntax: 


Interactive Graphics 


GLint glRenderMode(GLenum mode) ; 


Description: 


Parameters: 


mode 


Returns: 


See Also: 


OpenGL operates in three modes when you call your drawing functions: 


GL_RENDER: Render mode (the default). Drawing functions result in pixels 
in the frame buffer. 


GL_SELECT: Selection mode. No changes to the frame buffer are made. 
Rather, hit records written to the selection buffer record primitives that 
would have been drawn within the viewing volume. The selection buffer 
must be allocated and specified first with a call to gl1SelectBuffer. 
GL_FEEDBACK: Feedback mode. No changes to the frame buffer are made. 
Instead, coordinates and attributes of vertices that would have been 
rendered in render mode are written to a feedback buffer. The feedback 
buffer must be allocated and specified first with a call to 
glFeedbackBuffer. 


GLenum: Specifies the rasterization mode. May be any one of GL_RENDER, 
GL_SELECT, or GL_FEEDBACK. The default value is GL_RENDER. 


The return value depends on the rasterization mode that was set the last 
time this function was called: 


GL_RENDER: Zero. 
GL_SELECT: The number of hit records written to the selection buffer. 


GL_FEEDBACK: The number of values written to the feedback buffer. Note 
that this is not the same as the number of vertices written. 


glFeedbackBuffer, glInitNames, glLoadName, glPassThrough, 
glPushName, glSelectBuffer 


glSelectBuffer 


Purpose: 
Include File: 
Syntax: 


Sets the buffer to be used for selection values. 
<gl.h> 


void glSelectBuffer(GLsizei size, GLuint *buffer) ; 


Description: 


When OpenGL is in selection mode (GL_SELECT), drawing commands do 
not produce pixels in the frame buffer. Instead, they produce hit records 
that are written to the selection buffer that is established by this func- 
tion. Each hit record consists of the following data: 


Reference 


¢ The number of names on the name stack when the hit occurred. 


¢ The minimum and maximum z values of all the vertices of the primi- 
tives that intersected the viewing volume. This value is scaled to range 
from 0.0 to 1.0. 


¢ The contents of the name stack at the time of the hit, starting with 
the bottom element. 


Parameters: 

size GLsize: The number of values that can be written into the buffer estab- 
lished by *buffer. 

buffer GLuint*: A pointer to memory that will contain the selection hit records. 

Returns: None. 

See Also: glFeedbackBuffer, glInitNames, glLoadName, glPushName, glRenderMode 

gluPickMatrix 

Purpose: Defines a picking region that can be used to identify user selections. 

Include File: <glu.h> 

Syntax: 

void gluPickMatrix(GLdouble x, GLdouble y, GLdouble width, GLdouble height, GLint 

viewport[4]); 

Description: This function creates a matrix that will define a smaller viewing volume 
based on screen coordinates for the purpose of selection. By using the 
mouse coordinates with this function in selection mode, you can deter- 
mine which of your objects are under or near the mouse cursor. The 
matrix created is multiplied by the current projection matrix. Typically, 
you should call glLoadIdentity before calling this function and then 
multiply the perspective matrix that you used to create the viewing 
volume in the first place. If you are using gluPickMatrix to pick NURBS 
surfaces, you must turn off the NURBS property GLU_AUTO_LOAD_MATRIX 
before using this function. 

Parameters: 

Ry GLdouble: The center of the picking region in window coordinates. 


width, height 


viewport 


GLdouble: The width and height of the desired picking region in window 
coordinates. 


GLint[4]: The current viewport. You can get the current viewport by 
calling glGetIntegerv with GL_VIEWPORT. 
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Returns: None. 


See Also: glGet, glLoadIdentity, glMultMatrix, glRenderMode, 
gluPerspective 


PART Il 
OpenGL Everywhere 


One of the most often touted features and advantages to using 
OpenGL for rendering is that it is widely available across oper- 
ating systems and hardware platforms. Although the core 
OpenGL functionality remains consistent, you will notice a few 
quirks when moving from one platform to another. So far, we 
have been using GLUT as a means of achieving source porta- 
bility for our sample programs. GLUT is fine for learning 
purposes, but professional software developers know that to 
build high-quality and feature-rich applications, it is often 
necessary to incorporate specific operating system features or 
support the GUI features that users expect of programs that run 
in their favorite environment. 


The next three chapters concern themselves with using 
OpenGL on three different but popular platforms. Each operat- 
ing system has its own advantages and quirks when it comes to 
using OpenGL. Each chapter begins by describing the common 
task of getting OpenGL up and running but then delves into 
some special features of OpenGL that are specific to the plat- 
form, as well as some notes on maximizing performance on 
that platform. 


OpenGL. It’s everywhere. Do the math. 


CHAPTER 13 
Wiggle: OpenGL on Windows 


by Richard S. Wright, Jr. 


WHAT YOU’LL LEARN IN THIS CHAPTER: 


How To Functions You'll Use 

Request and select an OpenGL pixel format ChoosePixelFormat/DescribePixelFormat/ 
SetPixelFormat 

Create and use OpenGL rendering contexts wglCreateContext/wglDeleteContext/ 
wglMakeCurrent 

Respond to window messages WM_PAINT/WM_CREATE/WM_DESTROY/WM_SIZE 

Use double buffering in Windows SwapBuffers 


OpenGL is purely a graphics API, with user interaction and the screen or window handled 
by the host environment. To facilitate this partnership, each environment usually has 
some extensions that “glue” OpenGL to its own window management and user interface 
functions. This glue is code that associates OpenGL drawing commands to a particular 
window. It is also necessary to provide functions for setting buffer modes, color depths, 
and other drawing characteristics. 


For Microsoft Windows, this glue code is embodied in a set of new functions added to the 
Windows API. They are called the wiggle functions because they are prefixed with wgl 
rather than gl. These gluing functions are explained in this chapter, where we dispense 
with using the GLUT library for our OpenGL framework and build full-fledged Windows 
applications that can take advantage of all the operating system’s features. You will see 
what characteristics a Windows window must have to support OpenGL graphics. You will 
learn which messages a well-behaved OpenGL window should handle and how. The 
concepts of this chapter are introduced gradually, as we build a model OpenGL program 
that provides a framework for Windows-specific OpenGL support. 


So far in this book, you’ve needed no prior knowledge of 3D graphics and only a rudimen- 
tary knowledge of C programming. For this chapter, however, we assume you have at least 
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an entry-level knowledge of Windows programming. Otherwise, we would have wound up 
writing a book twice the size of this one, and we would have spent more time on the 
details of Windows programming and less on OpenGL programming. If you are new to 
Windows, or if you cut your teeth on one of the application frameworks and aren’t all 
that familiar with Windows procedures, message routing, and so forth, you might want to 
check out some of the recommended reading in Appendix A, “Further Reading,” before 
going too much further in this chapter. 


OpenGL Implementations on Windows 


OpenGL became available for the Win32 platform with the release of Windows NT version 
3.5. It was later released as an add-on for Windows 95 and then became a shipping part of 
the Windows 95 operating system (OSR2). OpenGL is now a native API on any Win32 
platform (Windows 95/98/ME, Windows NT/2000/XP/2003), with its functions exported 
from openg132.d11. You need to be aware of four flavors of OpenGL on Windows: 
Generic, ICD, MCD, and the Extended. Each has its pros and cons from both the user and 
developer point of view. You should at least have a high-level understanding of how these 
implementations work and what their drawbacks might be. 


Generic OpenGL 


A generic implementation of OpenGL is simply a software implementation that does not 
use specific 3D hardware. The Microsoft implementation bundled with Windows is a 
generic implementation. The Silicon Graphics Incorporated (SGI) OpenGL for Windows 
implementation (no longer widely available) optionally made use of MMxX instructions, 
but it was not considered dedicated 3D hardware, so it was still considered a generic soft- 
ware implementation. Another implementation called MESA (ww.mesa3d.org) is not 
strictly a “real” OpenGL implementation—it’s a “work-a-like”—but for most purposes, you 
can consider it to be so. MESA can also be hooked to hardware, but this should be consid- 
ered a special case of the mini-driver (discussed shortly). 


Although the MESA implementation has kept up with OpenGL’s advancing feature set 
over the years, the Microsoft generic implementation has not been updated since OpenGL 
version 1.1. Not to worry, we will soon show you how to get to all the OpenGL function- 
ality your graphics card supports. 


Installable Client Driver 


The Installable Client Driver (ICD) was the original hardware driver interface provided for 
Windows NT. The ICD must implement the entire OpenGL pipeline using a combination 
of software and the specific hardware for which it was written. Creating an ICD from 
scratch is a considerable amount of work for a vendor to undertake. 


The ICD drops in and works with Microsoft’s OpenGL implementation. Applications 
linked to openg132.d11 are automatically dispatched to the ICD driver code for OpenGL 


OpenGL Implementations on Windows 


calls. This mechanism is ideal because applications do not have to be recompiled to take 
advantage of OpenGL hardware should it become available. The ICD is actually a part of 
the display driver and does not affect the existing openGL32.d11 system DLL. This driver 
model provides the vendor with the most opportunities to optimize its driver and hard- 

ware combination. 


Mini-Client Driver 


The Mini-Client Driver (MCD) was a compromise between a software and hardware imple- 
mentation. Most early PC 3D hardware provided hardware-accelerated rasterization only. 
(See “The “Pipeline” section in Chapter 2, “Using OpenGL.”) The MCD driver model 
allowed applications to use Microsoft’s generic implementation for features that were not 
available in hardware. For example, transform and lighting could come from Microsoft's 
OpenGL software, but the actual rendering of lit shaded triangles would be handled by the 
hardware. 


The MCD driver implementation made it easy for hardware vendors to create OpenGL 
drivers for their hardware. Most of the work was done by Microsoft, and whatever features 
the vendors did not implement in hardware was handed back to the Microsoft generic 
implementation. 


The MCD driver model showed great promise for bringing OpenGL to the PC mass 
market. Initially available for Windows NT, a software development kit (SDK) was provided 
to hardware vendors to create MCD drivers for Windows 95. After many hardware vendors 
had completed their MCD drivers, Microsoft decided not to license the code for public 
release. This gave their own proprietary 3D API a temporary advantage in the consumer 
marketplace. 


The MCD driver model today is largely obsolete, but a few implementations are still in 
use. One reason for its demise is that the MCD driver model cannot support Intel’s 
Accelerated Graphics Port (AGP) texturing efficiently. Another is that SGI began providing 
an optimized ICD driver kit to vendors that made writing ICDs almost as easy as writing 
MCDs. (This move was a response to Microsoft’s temporary withdrawal of support for 
OpenGL on Windows 95.) This driver kit and model has now replaced the MCD model 
and SDK. 


Mini-Driver 

A mini-driver is not a real display driver. Instead, it is a drop-in replacement for 
openg132.d11 that makes calls to a hardware vendor’s proprietary 3D hardware driver. 
Typically, these mini-drivers convert OpenGL calls to roughly equivalent calls in a 
vendor's proprietary 3D API. The first mini-driver was written by 3Dfx for its Voodoo 
graphics card. This DLL drop-in converted OpenGL calls into the Voodoo’s native Glide 
(the 3Dfx 3D API) programming interface. 
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Id software first wrote a version of its popular game Quake that used OpenGL and ran 
with this 3Dfx mini-driver. For this reason, as mini-drivers were developed for other 
graphics cards, they were sometimes called “Quake drivers.” Many of the higher-end 
OpenGL hardware vendors would sarcastically refer to the consumer boards as “Quake 
accelerators,” not worthy of comparison to their hardware. Many other game hardware 
vendors hopped on the bandwagon and began supplying mini-drivers for their hardware, 
too. Although they popularized OpenGL for games, mini-drivers often had missing 
OpenGL functions or features. Any application that used OpenGL did not necessarily work 
with a mini-driver. Typically, these drivers provided only the barest functionality needed 
to run a popular game. 


Fortunately, the widespread popularity of OpenGL has made the mini-driver obsolete on 
newer commodity PCs. You may still come across this beast, however, in older PCs or 
installations using older graphics hardware. One persisting incarnation of the mini-driver 
is the wrapper DLL that takes OpenGL function calls and converts them to Direct 3D func- 
tionality. 


Extended OpenGL 


If you are developing software for any version of Microsoft Windows, you are most likely 
making use of header files and an import library that works with Microsoft's 
openg132.d11. This DLL is designed to provide a generic (software-rendered) fallback if 3D 
hardware is not installed, and as a dispatch mechanism that works with the official 
OpenGL driver model for hardware-based OpenGL implementations. Using this header 
and import library alone gives you access only to functions and capabilities present in 
OpenGL 1.1. 


In the introduction, we outlined for you the features that have been added to OpenGL 
since 1.1 up until OpenGL 2.0 with a fully integrated shading language. Take note, 
however, that OpenGL 1.1 is still a very capable and full-featured graphics API and is suit- 
able for a wide range of graphical applications, including games or business graphics. Even 
without the additional features of OpenGL 1.2 and beyond, graphics hardware perfor- 
mance has increased exponentially, and most PC graphics cards have the entire OpenGL 
pipeline implemented in special-purpose hardware. OpenGL 1.1 can still produce scream- 
ing fast and highly complex 3D renderings! 


Many applications still will require or at least be significantly enhanced by making use of 
the newer OpenGL innovations. To get to the newer OpenGL features (which are widely 
supported), you need to use the same OpenGL extension mechanism that you use to get 
to vendor-specific OpenGL enhancements. OpenGL extensions were introduced in 
Chapter 2, and the specifics of using this extension mechanism on Windows are covered 
later in this chapter in the section “OpenGL and WGL Extensions.” 


This may sound like a bewildering environment in which to develop 3D graphics— 
especially if you plan to port your applications to say, the Macintosh platform, where 
OpenGL features are updated more consistently with each OS release. Some strategies, 


Basic Windows Rendering 


however, can make such development more manageable. First, you can call the following 
function so your application can tell at runtime which OpenGL version the hardware 
driver supports: 


glGetString(GL_VERSION) ; 


This way, you can gracefully decide whether the application is going to be able to run at 
all on the user’s system. Because OpenGL and its extensions are dynamically loaded, there 
is no reason your programs should not at least start and present the user with a friendly 
and informative error or diagnostic message. 


You also need to think carefully about what OpenGL features your application must have. 
Can the application be written to use only OpenGL 1.1 features? Will the application be 
usable at all if no hardware is present and the user must use the built-in software renderer? 
If the answer to either of these questions is yes, you should first write your application’s 
rendering code using only the import library for OpenGL 1.1. This gives you the widest 
possible audience for your application. 


When you have the basic rendering code in place, you can go back and consider perfor- 
mance optimizations or special visual effects available with newer OpenGL features that 
you want to make available in your program. By checking the OpenGL version early in 
your program, you can introduce different rendering paths or functions that will option- 
ally perform better or provide additional visual effects to your rendering. For example, 
static texture maps could be replaced with fragment programs, or standard fog replaced 
with volumetric fog made possible through vertex programs. Using the latest and greatest 
features allows you to really show off your program, but if you rely on them exclusively, 
you may be severely limiting your audience...and sales. 


Sometimes, however, your application really must have some newer OpenGL feature. For 
example, a medical visualization package may require that 3D texturing or the imaging 
subset be available. In these types of more specialized or vertical markets, your application 
will simply have to require some minimal OpenGL support to run. The OpenGL version 
required in these cases will be listed among any other minimum system requirements that 
you specify are needed for your software. Again, your application can check for these 
details at startup. 
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The GLUT library provided only one window, and OpenGL function calls always produced 
output in that window. (Where else would they go?) Your own real-world Windows appli- 
cations, however, will often have more than one window. In fact, dialog boxes, controls, 
and even menus are actually windows at a fundamental level; having a useful program 
that contains only one window is nearly impossible. How does OpenGL know where to 
draw when you execute your rendering code? Before we answer this question, let’s first 
review how we normally draw in a window without using OpenGL. 
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GDI Device Contexts 


Normally, when you draw in a window without using OpenGL, you use the Windows 
Graphics Device Interface (GDI) functions. Each window has a device context that actually 
receives the graphics output, and each GDI function takes a device context as an argument 
to indicate which window you want the function to affect. You can have multiple device 
contexts, but only one for each window. 


The sample program WINRECT on the companion CD draws an ordinary window with a 
blue background and a red square in the center. The output from this program, shown in 
Figure 13.1, should look familiar to you. This is nearly the same image produced by the 
second OpenGL program in Chapter 2, GLRECT. Unlike that earlier example, however, the 
WINRECT program does not use GLUT; we wrote it entirely with the Windows API. This 
code is relatively generic as far as Windows programming goes. A WinMain function gets 
things started and keeps the message pump going, and a WndProc function handles 
messages for the main window. 


FIGURE 13.1 Output from WINRECT. 


Your familiarity with Windows programming should extend to the details of creating and 
displaying a window, so we cover only the code from this example that is responsible for 
drawing the background and square, and won't list the entire program here. 


First, you must create a blue and a red brush for filling and painting. The handles for these 
brushes are declared globally: 


// Handles to GDI brushes we will use for drawing 
HBRUSH hBlueBrush,hRedBrush; 


Then you create the brushes in the WinMain function, using the RGB macro to create solid 
red and blue brushes: 


// Create a blue and red brush for drawing and filling 
// operations. // Red, green, blue 
hBlueBrush = CreateSolidBrush(RGB( 2, Q, 255)); 
hRedBrush = CreateSolidBrush(RGB( 255, Q, @)); 
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When you specify the window style, you set the background to use the blue brush in the 
window class structure: 


we.hbrBackground = hBlueBrush; // Use blue brush for background 


Window size and position (previously set with glutPositionWindow and 
glutReshapeWindow) are set when the window is created: 


// Create the main application window 
hWnd = CreateWindow( 
lpszAppName , 
lpszAppName, 
WS_OVERLAPPEDWINDOW, 
100, 100, // Size and dimensions of window 
250, 250, 
NULL, 
NULL, 
hInstance, 
NULL) ; 
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Finally, the actual painting of the window interior is handled by the WM_PAINT message 
handler in the WndProc function: 


case WM_PAINT: 
{ 
PAINTSTRUCT ps; 
HBRUSH hOldBrush; 


// Start painting 
BeginPaint (hWnd, &ps) ; 


// Select and use the red brush 
hOldBrush = SelectObject(ps.hdc,hRedBrush) ; 


// Draw a rectangle filled with the currently 
// selected brush 
Rectangle(ps.hdc, 100,100, 150,150); 


// Deselect the brush 
SelectObject(ps.hdc,hOldBrush) ; 


// End painting 
EndPaint (hWnd, &ps) ; 
} 

break; 
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The call to BeginPaint prepares the window for painting and sets the hdc member of the 
PAINTSTRUCT structure to the device context to be used for drawing in this window. This 
handle to the device context is used as the first parameter to all GDI functions, identifying 
which window they should operate on. This code then selects the red brush for painting 
operations and draws a filled rectangle at the coordinates (100,100,150,150). Then the 
brush is deselected, and EndPaint cleans up the painting operation for you. 


Before you jump to the conclusion that OpenGL should work in a similar way, remember 
that the GDI is Windows specific. Other environments do not have device contexts, 
window handles, and the like. Although the ideas may be similar, they are certainly not 
called the same thing and might work and behave differently. OpenGL, on the other 
hand, was designed to be completely portable among environments and hardware plat- 
forms (and it didn’t start on Windows anyway!). Adding a device context parameter to the 
OpenGL functions would render your OpenGL code useless in any environment other 
than Windows. 


OpenGL does have a context identifier, however, and it is called the rendering context. The 
rendering context is similar in many respects to the GDI device context because it is the 
rendering context that remembers current colors, state settings, and so on, much like the 
device context holds onto the current brush or pen color. 


Pixel Formats 


The Windows concept of the device context is limited for 3D graphics because it was 
designed for 2D graphics applications. In Windows, you request a device context identifier 
for a given window. The nature of the device context depends on the nature of the device. 
If your desktop is set to 16-bit color, the device context Windows gives you knows about 
and understands 16-bit color only. You cannot tell Windows, for example, that one 
window is to be a 16-bit color window and another is to be an 8-bit color window. 


Although Windows lets you create a memory device context, you still have to give it an 
existing window device context to emulate. Even if you pass in NULL for the window para- 
meter, Windows uses the device context of your desktop. You, the programmer, have no 
control over the intrinsic characteristics of a windows device context. 


Any window or device that will be rendering 3D graphics has far more characteristics to it 
than simply color depth, especially if you are using a hardware rendering device (3D 
graphics card). Up until now, GLUT has taken care of these details for you. When you 
initialized GLUT, you told it what buffers you needed (double or single color buffer, depth 
buffer, stencil, and alpha). 


Before OpenGL can render into a window, you must first configure that window according 
to your rendering needs. Do you want hardware or software rendering? Will the rendering 
be single or double buffered? Do you need a depth buffer? How about stencil, destination 
alpha, or an accumulation buffer? After you set these parameters for a window, you 
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cannot change them later. To switch from a window with only a depth and color buffer to 
a window with only a stencil and color buffer, you have to destroy the first window and 
re-create a new window with the characteristics you need. 


Describing a Pixel Format 

The 3D characteristics of the window are set one time, usually just after window creation. 
The collective name for these settings is the pixel format. Windows provides a structure 
named PIXELFORMATDESCRIPTOR that describes the pixel format. This structure is defined as 
follows: 


typedef struct tagPIXELFORMATDESCRIPTOR { 


WORD nSize; // Size of this structure 

WORD nVersion; // Version of structure (should be 1) 

DWORD dwFlags; // Pixel buffer properties 

BYTE iPixelType; // Type of pixel data (RGBA or Color Index) 
BYTE cColorBits; // Number of color bit planes in color buffer 
BYTE cRedBits; // How many bits for red 

BYTE cRedShift; // Shift count for red bits 

BYTE cGreenBits; // How many bits for green 

BYTE cGreenShift; // Shift count for green bits 

BYTE cBlueBits; // How many bits for blue 

BYTE cBlueShift; // Shift count for blue 

BYTE cAlphaBits; // How many bits for destination alpha 
BYTE cAlphaShift; // Shift count for destination alpha 

BYTE cAccumBits; // How many bits for accumulation buffer 


BYTE cAccumRedBits; // How many red bits for accumulation buffer 

BYTE cAccumGreenBits; // How many green bits for accumulation buffer 
BYTE cAccumBlueBits; // How many blue bits for accumulation buffer 
BYTE cAccumAlphaBits; // How many alpha bits for accumulation buffer 


BYTE cDepthBits; // How many bits for depth buffer 

BYTE cStencilBits; // How many bits for stencil buffer 

BYTE cAuxBuffers; // How many auxiliary buffers 

BYTE iLayerType; // Obsolete - ignored 

BYTE bReserved; // Number of overlay and underlay planes 
DWORD dwLayerMask; // Obsolete - ignored 

DWORD dwVisibleMask; // Transparent color of underlay plane 
DWORD dwDamageMask ; // Obsolete - ignored 


} PIXELFORMATDESCRIPTOR; 


For a given OpenGL device (hardware or software), the values of these members are not 
arbitrary. Only a limited number of pixel formats is available for a given window. Pixel 
formats are said to be exported by the OpenGL driver or software renderer. Most of these 
structure members are self-explanatory, but a few require some additional explanation: 
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nSize 
nVersion 


dwFlags 


iPixelType 


cColorBits 


cRedBits 


cGreenBits 


cBlueBits 


cAlphaBits 


cAccumBits 


cDepthBits 


cStencilBits 


cAuxBuf fers 


iLayerType 


bReserved 


The size of the structure; set to sizeof (PIXELFORMATDESCRIPTOR) ;. 
Set to 1. 


A set of bit flags that specify properties of the pixel buffer. Most of these 
flags are not mutually exclusive, but a few are used only when requesting 
or describing the pixel format. Table 13.1 lists the valid flags for this 
member. 


The type of color buffer. Only two values are valid: PFD_TYPE_RGBA and 
PFD_TYPE_COLORINDEX. PFD_TYPE_COLORINDEX allows you to request or 
describe the pixel format as color index mode. This rendering mode 
should be considered obsolete on modern PC hardware. 


The number of bits of color depth in the color buffer. Typical values are 8, 
16, 24, and 32. The 32-bit color buffers may or may not be used to store 
destination alpha values. Only Microsoft's generic implementation on 
Windows 2000, Windows XP, and later supports destination alpha. 


The number of bits in the color buffer dedicated for the red color compo- 
nent. 


The number of bits in the color buffer dedicated for the green color 
component. 


The number of bits in the color buffer dedicated for the blue color 
component. 


The number of bits used for the alpha buffer. Destination alpha is not 
supported by Microsoft’s generic implementation, but many hardware 
implementations are beginning to support it. 


The number of bits used for the accumulation buffer. 


The number of bits used for the depth buffer. Typical values are 0, 16, 24, 
and 32. The more bits dedicated to the depth buffer, the more accurate 
depth testing will be. 


The number of bits used for the stencil buffer. 


The number of auxiliary buffers. In implementations that support auxiliary 
buffers, rendering can be redirected to an auxiliary buffer from the color 
buffer and swapped to the screen at a later time. 


Obsolete (ignored). 


The number of overlay and underlay planes supported by the implemen- 
tation. Bits 0 through 3 specify the number of overlay planes (up to 15), 
and bits 4 through 7 specify the number of underlay planes (also up 

to 15). 


dwLayerMask 
dwVisibleMask 


dwDamageMask 


Bit Flag 


PFD_DRAW_TO_WINDOW 
PFD_DRAW_TO_BITMAP 
PFD_SUPPORT_GDI 


PFD_SUPPORT_OPENGL 


PFD_GENERIC_ACCELERATED 


PFD_GENERIC_FORMAT 


PFD_NEED_PALETTE 


PFD_NEED_SYSTEM_PALETTE 


PFD_DOUBLEBUFFER 


PFD_STEREO 


PFD_SWAP_LAYER_BUFFERS 


PFD_DEPTH_DONTCARE 


PFD_DOUBLE_BUFFER_DONTCARE 
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Obsolete (ignored). 
The transparent color of an underlay plane. 


Obsolete (ignored). 


TABLE 13.1 Valid Flags to Describe the Pixel Rendering Buffer 


Description 


The buffer’s output is displayed in a window. 

The buffer’s output is written to a Windows bitmap. 

The buffer supports Windows GDI drawing. Most implementations 
allow this only for single-buffered windows or bitmaps. 

The buffer supports OpenGL drawing. 

The buffer is accelerated by an MCD device driver that accelerates 
this format. 

The buffer is a rendered by a software implementation. This bit is 
also set with PFD_GENERIC_ACCELERATED for MCD drivers. Only if 
this bit is clear is the hardware driver an ICD. 

The buffer is on a palette-managed device. This flag is set on 
Windows when running in 8-bit (256-color) mode and requires a 3- 
3-2 color palette. 

This flag indicates that OpenGL hardware supports rendering in 
256-color mode. A 3-3-2 palette must be realized to enable hard- 
ware acceleration. Although documented, this flag can be consid- 
ered obsolete. No mainstream hardware accelerator that supported 
accelerated rendering in 256-color mode ever shipped for Windows. 
The color buffer is double buffered. 

The color buffer is stereoscopic. This is not supported by Microsoft’s 
generic implementation. Most PC vendors that support stereo do so 
with custom extensions for their hardware. 

This flag is used if overlay and underlay planes are supported. If set, 
these planes may be swapped independently of the color buffer. 
This flag is used only when requesting a pixel format. It indicates 
that you do not need a depth buffer. Some implementations can 
save memory and enhance performance by not allocating memory 
for the depth buffer. 

This flag is used only when requesting a pixel format. It indicates 
that you do not plan to use double buffering. Although you can 
force rendering to the front buffer only, this flag allows an imple- 
mentation to save memory and potentially enhance performance. 
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Enumerating Pixel Formats 

The pixel format for a window is identified by a one-based integer index number. An 
implementation exports a number of pixel formats from which to choose. To set a pixel 
format for a window, you must select one of the available formats exported by the driver. 
You can use the DescribePixelFormat function to determine the characteristics of a given 
pixel format. You can also use this function to find out how many pixel formats are 
exported by the driver. The following code shows how to enumerate all the pixel formats 
available for a window: 


PIXELFORMATDESCRIPTOR pfd; // Pixel format descriptor 
int nFormatCount; // How many pixel formats exported 


// Get the number of pixel formats 

// Will need a device context 

pfd.nSize = sizeof (PIXELFORMATDESCRIPTOR) ; 
nFormatCount = DescribePixelFormat(hDC, 1, ®, NULL); 


// Retrieve each pixel format 

for(int i = 1; i <= nFormatCount; i++) 
{ 
// Get description of pixel format 
DescribePixelFormat(hDC, i, pfd.nSize, &pfd); 


} 


The DescribePixelFormat function returns the maximum pixel format index. You can use 
an initial call to this function as shown to determine how many are available. The CD 
includes an interesting utility program called GLView for this chapter. This program 
enumerates all pixel formats available for your display driver for the given resolution and 
color depths. Figure 13.2 shows the output from this program when a double-buffered 
pixel format is selected. (A single-buffered pixel format would contain a blinking block 
animation.) 


The Microsoft Foundation Classes (MFC) source code is included on the CD for GLView. 
This is a bit more complex than your typical sample program, and GLView is provided 
more as a tool for your use than as a programming example. The important code for 
enumerating pixel formats was presented earlier and is less than a dozen lines long. If you 
are familiar with MFC already, examination of this source code will show you how to inte- 
grate OpenGL rendering into any CWnd derived window class. 
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FIGURE 13.2 The GLView program shows all pixel formats for a given device. 


The list box lists all the available pixel formats and displays their characteristics (driver 
type, color depth, and so on). A sample window in the lower-right corner displays a rotat- 
ing cube using a window created with the highlighted pixel format. The g1GetString 
function enables you to find out the name of the vendor for the OpenGL driver, as well as 
other version information. Finally, a list box displays all the OpenGL and WGL extensions 
exported by the driver (WGL extensions are covered later in this chapter). 


If you experiment with this program, you'll discover that not all pixel formats can be used 
to create an OpenGL window, as shown in Figure 13.3. Even though the driver exports 
these pixel formats, it does not mean that you can create an OpenGL-enabled window 
with one of them. The most important criterion is that the pixel format color depth must 
match the color depth of your desktop. That is, you can’t create a 16-bit color pixel format 
for a 32-bit color desktop, or vice versa. 


Make special note of the fact that at least 24 pixel formats are always enumerated, some- 
times more. If you are running the Microsoft generic implementation, you will see exactly 
24 pixel formats listed (all belonging to Microsoft). If you have a hardware accelerator 
(either an MCD or ICD), you'll note that the accelerated pixel formats are listed first, 
followed by the 24 generic pixel formats belonging to Microsoft. This means that when 
hardware acceleration is present, you actually can choose from two implementations of 
OpenGL. The first are the hardware-accelerated pixel formats belonging to the hardware 
accelerator. The second are the pixel formats for Microsoft’s software implementation. 


Knowing this bit of information can be useful. For one thing, it means that a software 
implementation is always available for rendering to bitmaps or printer devices. It also 
means that if you so desire (for debugging purposes, perhaps), you can force software 

rendering, even when an application might typically select hardware acceleration. 
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FIGURE 13.3 The GLView program showing an invalid pixel format. 


Selecting and Setting a Pixel Format 

Enumerating all the available pixel formats and examining each one to find one that 
meets your needs could turn out to be quite tedious. Windows provides a shortcut func- 
tion that makes this process somewhat simpler. The ChoosePixelFormat function allows 
you to create a pixel format structure containing the desired attributes of your 3D window. 
The ChoosePixelFormat function then finds the closest match possible (with preference 
for hardware-accelerated pixel formats) and returns the most appropriate index. The pixel 
format is then set with a call to another new Windows function, SetPixelFormat. The 
following code segment shows the use of these two functions: 


int nPixelFormat; 


static PIXELFORMATDESCRIPTOR pfd = { 
sizeof (PIXELFORMATDESCRIPTOR), // Size of this structure 
A // Version of this structure 
PFD_DRAW_TO_WINDOW // Draw to window (not to bitmap) 
PFD_SUPPORT_OPENGL // Support OpenGL calls in window 


PFD_DOUBLEBUFFER, // Double buffered mode 
PFD_TYPE_RGBA, // RGBA color mode 

92, // Want 32-bit color 
0,0,0,0,0,0, // Not used to select mode 
0,0, // Not used to select mode 
0,0,0,0,0, // Not used to select mode 


16, // Size of depth buffer 
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Q, // No stencil 

Q, // No auxiliary buffers 

Q, // Obsolete or reserved 

Q, // No overlay and underlay planes 

Q, // Obsolete or reserved layer mask 

e, // No transparent color for underlay plane 
0}; // Obsolete 


// Choose a pixel format that best matches that described in pfd 
// for the given device context 
nPixelFormat = ChoosePixelFormat(hDC, &pfd); 


// Set the pixel format for the device context 
SetPixelFormat(hDC, nPixelFormat, &pfd); 


Initially, the PIXELFORMATDESCRIPTOR structure is filled with the desired characteristics of 
the 3D-enabled window. In this case, you want a double-buffered pixel format that renders 
into a window, so you request 32-bit color and a 16-bit depth buffer. If the current imple- 
mentation supports 24-bit color at best, the returned pixel format will be a valid 24-bit 
color format. Depth buffer resolution is also subject to change. An implementation might 
support only a 24-bit or 32-bit depth buffer. In any case, ChoosePixelFormat always 
returns a valid pixel format, and if at all possible, it returns a hardware-accelerated pixel 
format. 


Some programmers and programming needs might require more sophisticated selection of 
a pixel format. In these cases, you need to enumerate and inspect all available pixel 
formats or use the WGL extension presented later in this chapter. For most uses, however, 
the preceding code is sufficient to prime your window to receive OpenGL rendering 
commands. 


The OpenGL Rendering Context 

A typical Windows application can consist of many windows. You can even set a pixel 
format for each one (using that windows device context) if you want! But SetPixelFormat 
can be called only once per window. When you call an OpenGL command, how does it 
know which window to send its output to? In the previous chapters, we used the GLUT 
framework, which provided a single window to display OpenGL output. Recall that with 
normal Windows GDI-based drawing, each window has its own device context. 


To accomplish the portability of the core OpenGL functions, each environment must 
implement some means of specifying a current rendering window before executing any 
OpenGL commands. Just as the Windows GDI functions use the windows device contexts, 
the OpenGL environment is embodied in what is known as the rendering context. Just as a 
device context remembers settings about drawing modes and commands for the GDI, the 
rendering context remembers OpenGL settings and commands. 
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You create an OpenGL rendering context by calling the wglCreateContext function. This 
function takes one parameter: the device context of a window with a valid pixel format. 
The data type of an OpenGL rendering context is HGLRC. The following code shows the 
creation of an OpenGL rendering context: 


HGLRC hRC; // OpenGL rendering context 
HDC hDC; // Windows device context 


// Select and set a pixel format 
hRC = wglCreateContext(hDC) ; 


A rendering context is created that is compatible with the window for which it was 
created. You can have more than one rendering context in your application—for instance, 
two windows that are using different drawing modes, perspectives, and so on. However, 
for OpenGL commands to know which window they are operating on, only one rendering 
context can be active at any one time per thread. When a rendering context is made 
active, it is said to be current. 


When made current, a rendering context is also associated with a device context and thus 
with a particular window. Now, OpenGL knows which window into which to render. You 
can even move an OpenGL rendering context from window to window, but each window 
must have the same pixel format. To make a rendering context current and associate it 
with a particular window, you call the wglMakeCurrent function. This function takes two 
parameters, the device context of the window and the OpenGL rendering context: 


void wglMakeCurrent(HDC hDC, HGLRC hRC); 


Putting It All Together 


We've covered a lot of ground over the past several pages. We’ve described each piece of 
the puzzle individually, but now let’s look at all the pieces put together. In addition to 
seeing all the OpenGL-related code, we should examine some of the minimum require- 
ments for any Windows program to support OpenGL. Our sample program for this section 
is GLRECT. It should look somewhat familiar because it is also the first GLUT-based sample 
program from Chapter 2. Now, however, the program is a full-fledged Windows program 
written with nothing but C and the Win32 API. Figure 13.4 shows the output of the new 
program, complete with bouncing square. 


Creating the Window 

The starting place for any Windows-based GUI program is the WinMain function. In this 
function, you register the window type, create the window, and start the message pump. 
Listing 13.1 shows the WinMain function for the first sample. 


FIGURE 13.4 Output from the GLRECT program with bouncing square. 


LISTING 13.1 The WinMain Function of the GLRECT Sample Program 
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// Entr 
int API 


{ 
MSG 


WND! 
HWN' 


// 
we. 
we 
we. 
we. 
we. 
we. 
we 


// 
we. 


wc 
we. 


/I 
if ( 


y point of all Windows programs 

ENTRY WinMain( HINSTANCE hInstance, 
HINSTANCE hPrevInstance, 
LPSTR lpCmdLine, 
int nCmdShow) 

msg; // Windows message structure 
CLASS wc; // Windows class structure 
D hWnd; // Storage for window handle 


Register window style 

style = CS_HREDRAW | CS_VREDRAW | CS_OWNDC; 
-lpfnWndProc = (WNDPROC) WndProc; 

cbClsExtra = Q; 

cbhbWndExtra = Q; 

hInstance = hInstance; 

hIcon = NULL; 

.hCursor = LoadCursor(NULL, IDC_ARROW) ; 

No need for background brush for OpenGL window 
hbrBackground = NULL; 

.lpszMenuName = NULL; 

lpszClassName = lpszAppName; 

Register the window class 


RegisterClass(&wc) == 0) 
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return FALSE; 


// Create the main application window 
hWnd = CreateWindow( 

lpszAppName, 

lpszAppName , 


// OpenGL requires WS_CLIPCHILDREN and WS_CLIPSIBLINGS 
WS_OVERLAPPEDWINDOW | WS_CLIPCHILDREN | WS_CLIPSIBLINGS, 


// Window position and size 
100, 100, 

250, 250, 

NULL, 

NULL, 

hInstance, 

NULL) ; 


// If window was not created, quit 
if (hWnd == NULL) 
return FALSE; 


// Display the window 
ShowWindow(hWnd , SW_SHOW) ; 
UpdateWindow( hWnd) ; 


// Process application messages until the application closes 
while( GetMessage(&msg, NULL, 0, 0)) 


{ 
TranslateMessage(&msg) ; 
DispatchMessage(&msgQg) ; 


} 


return msg.wParam; 


} 


This listing pretty much contains your standard Windows GUI startup code. Only two 
points really bear mentioning here. The first is the choice of window styles set in 
CreateWindow. You can generally use whatever window styles you like, but you do need to 
set the WS_CLIPCHILDREN and WS_CLIPSIBLINGS styles. These styles were required in earlier 
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versions of Windows, but later versions have dropped them as a strict requirement. The 
purpose of these styles is to keep the OpenGL rendering context from rendering into other 
windows, which can happen in GDI. However, an OpenGL rendering context must be 
associated with only one window at a time. 


The second note you should make about this startup code is the use of CS_OWNDC for the 
window style. Why you need this innocent-looking flag requires a bit more explanation. 
You need a device context for both GDI rendering and for OpenGL double-buffered page 
flipping. To understand what CS_OWNDC has to do with this, you first need to take a step 
back and review the purpose and use of a windows device context. 


First, You Need a Device Context 

Before you can draw anything in a window, you first need a windows device context. You 
need it whether you’re doing OpenGL, GDI, or even DirectX programming. Any drawing 
or painting operation in Windows (even if you’re drawing on a bitmap in memory) 
requires a device context that identifies the specific object being drawn on. You retrieve 
the device context to a window with a simple function call: 


HDC hDC = GetDC (hWnd) ; 


The hd¢ variable is your handle to the device context of the window identified by the 
window handle hWnd. You use the device context for all GDI functions that draw in the 
window. You also need the device context for creating an OpenGL rendering context, 
making it current, and performing the buffer swap. You tell Windows that you don’t need 
the device context for the window any longer with another simple function call, using the 
same two values: 


ReleaseDC(hWnd ,hDC); 


The standard Windows programming wisdom is that you retrieve a device context, use it 
for drawing, and then release it again as soon as possible. This advice dates back to the 
pre-Win32 days; under Windows 3.1 and earlier, you had a small pool of memory allo- 
cated for system resources, such as the windows device context. What happened when 
Windows ran out of system resources? If you were lucky, you got an error message. If 
you were working on something really important, the operating system could somehow 
tell, and it would instead crash and take all your work with it. Well, at least it seemed 
that way! 


The best way to spare your users this catastrophe was to make sure that the GetDc function 
succeeded. If you did get a device context, you did all your work as quickly as possible 
(typically within one message handler) and then released the device context so that other 
programs could use it. The same advice applied to other system resources such as pens, 
fonts, brushes, and so on. 
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Enter Win32 

Windows NT and the subsequent Win32-based operating systems were a tremendous bless- 
ing for Windows programmers, in more ways than can be recounted here. Among their 
many benefits was that you could have all the system resources you needed until you 
exhausted available memory or your application crashed. (At least it wouldn’t crash the 
OS!) It turns out that the GetDC function is, in computer time, quite an expensive function 
call to make. If you got the device context when the window was created and hung on to 
it until the window was destroyed, you could speed up your window painting consider- 
ably. You could hang on to brushes, fonts, and other resources that would have to be 
created or retrieved and potentially reinitialized each time the window was invalidated. 


One popular example of this Win32 benefit was a program that created random rectangles 
and put them in random locations in the window. (This was a GDI sample.) The difference 
between code written the old way and code written the new way was astonishingly 
obvious. Wow! Win32 was great! 


Three Steps Forward, Two Steps Back 

Windows 95, 98, and ME brought Win32 programming to the mainstream, but still had a 
few of the old 16-bit limitations deep down in the plumbing. The situation with losing 
system resources was considerably improved, but it was not eliminated entirely. The oper- 
ating system could still run out of resources, but (according to Microsoft) it was unlikely. 
Alas, life is not so simple. Under Windows NT, when an application terminates, all allo- 
cated system resources are automatically returned to the operating system. Under 
Windows 95, 98, or ME, you have a resource leak if the program crashes or the application 
fails to release the resources it allocated. Eventually, you will start to stress the system, and 
you can run out of system resources (or device contexts). 


What happens when Windows doesn’t have enough device contexts to go around? Well, it 
just takes one from someone who is being a hog with them. This means that if you call 
GetDC and don’t call ReleaseDC, Windows 95, 98, or ME might just appropriate your 
device context when it becomes stressed. The next time you call wg1MakeCurrent or 
SwapBuffers, your device context handle might not be valid. Your application might crash 
or mysteriously stop rendering. Ask someone in customer support how well it goes over 
when you try to explain to a customer that his or her problem with your application is 
really Microsoft’s fault! 


All Is Not Lost 

You actually have a way to tell Windows to create a device context just for your window’s 
use. This feature is useful because every time you call GetDC, you have to reselect your 
fonts, the mapping mode, and so on. If you have your own device context, you can do 
this sort of initialization only once. Plus, you don’t have to worry about your device 
context handle being yanked out from under you. Doing this is simple: You simply specify 
CS_OWNDC as one of your class styles when you register the window. A common error is to 
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use CS_OWNDC as a window style when you call Create. There are window styles and there 
are class styles, but you can’t mix and match. 


Code to register your window style generally looks something like this: 


WNDCLASS we; // Windows class structure 


// Register window style 
we.style = CS_HREDRAW | CS_VREDRAW | CS_OWNDC; 
wc.lpfnWndProc = (WNDPROC) WndProc; 


wc.lpszClassName = lpszAppName; 
// Register the window class 
if (RegisterClass(&wc) == Q) 
return FALSE; 


You then specify the class name when you create the window: 


hWnd = CreateWindow( wc.lpszClassName, szWindowName, ... 


Graphics programmers should always use CS_OWNDC in the window class registration. This 
ensures that you have the most robust code possible on any Windows platform. Another 
consideration is that many older OpenGL hardware drivers have bugs because they expect 
CS_OWNDC to be specified. They might have been originally written for NT, so the drivers do 
not account for the possibility that the device context might become invalid. The driver 
might also trip up if the device context does not retain its configuration (as is the case in 
the GetDC/ReleaseDC scenario). 


Regardless of the specifics, some drivers are not very stable unless you specify the 
CS_OWNDC flag. Many, if not most, vendors are addressing this well-known issue as their 
drivers mature. Still, the other reasons outlined here provide plenty of incentive to make 
what is basically a minor code adjustment. 


Using the OpenGL Rendering Context 

The real meat of the GLRECT sample program is in the window procedure, WndProc. The 
window procedure receives window messages from the operating system and responds 
appropriately. This model of programming, called message or event-driven programming, is 
the foundation of the modern Windows GUI. 


When a window is created, it first receives a WM_CREATE message from the operating 
system. This is the ideal location to create and set up the OpenGL rendering context. A 
window also receives a WM_DESTROY message when it is being destroyed. Naturally, this is 
the ideal place to put cleanup code. Listing 13.2 shows the SetDCPixelFormat format, 
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which is used to select and set the pixel format, along with the window procedure for the 
application. This function contains the same basic functionality that we have been using 
with the GLUT framework. 


LISTING 13.2 Setting the Pixel Format and Handling the Creation and Deletion of the 
OpenGL Rendering Context 


LILTTTTTTL TTT TTT TTT 
// Select the pixel format for a given device context 
void SetDCPixelFormat(HDC hDC) 

{ 


int nPixelFormat; 


static PIXELFORMATDESCRIPTOR pfd = { 
sizeof (PIXELFORMATDESCRIPTOR), // Size of this structure 
is // Version of this structure 
PFD_DRAW_TO_WINDOW // Draw to window (not to bitmap) 
PFD_SUPPORT_OPENGL // Support OpenGL calls in window 


PFD_DOUBLEBUFFER, // Double-buffered mode 
PFD_TYPE_RGBA, // RGBA color mode 

32, // Want 32-bit color 
@,0,0,0,0,0, // Not used to select mode 
0,0, // Not used to select mode 
0,0,0,0,0, // Not used to select mode 
16, // Size of depth buffer 

Q, // Not used here 

Q, // Not used here 

Q, // Not used here 

Q, // Not used here 

0,0, }; // Not used here 


// Choose a pixel format that best matches that described in pfd 
nPixelFormat = ChoosePixelFormat(hDC, &pfd); 


// Set the pixel format for the device context 
SetPixelFormat(hDC, nPixelFormat, &pfd); 
} 


TETTTTT TTT TTT TATA 
// Window procedure, handles all messages for this program 
LRESULT CALLBACK WndProc(HWND hWnd, 

UINT message, 

WPARAM wParam, 

LPARAM 1Param) 
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LISTING 13.2 Continued 


{ 
static HGLRC hRC = NULL; // Permanent rendering context 
static HDC hDC = NULL; // Private GDI device context 


switch (message) 
{ 
// Window creation, set up for OpenGL 
case WM_CREATE: 
// Store the device context 
hDC = GetDC(hWnd) ; 


// Select the pixel format 
SetDCPixelFormat(hDC) ; 


// Create the rendering context and make it current 
hRC = wglCreateContext(hDC) ; 
wglMakeCurrent(hDC, hRC); 


// Create a timer that fires 30 times a second 
SetTimer(hWnd,33,1,NULL) ; 
break; 


// Window is being destroyed, clean up 
case WM_DESTROY: 
// Kill the timer that we created 
KillTimer (hWnd, 101) ; 


// Deselect the current rendering context and delete it 
wglMakeCurrent(hDC,NULL) ; 
wglDeleteContext (hRC) ; 


// Tell the application to terminate after the window 
// is gone. 

PostQuitMessage(Q) ; 

break; 


// Window is resized. 

case WM_SIZE: 
// Call our function which modifies the clipping 
// volume and viewport 
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LISTING 13.2 Continued 


ChangeSize(LOWORD(1Param), HIWORD(1Param) ) ; 
break; 


// Timer moves and bounces the rectangle, simply calls 
// our previous OnIdle function, then invalidates the 
// window so it will be redrawn. 

case WM_TIMER: 


{ 
IdleFunction(); 


InvalidateRect (hWnd, NULL, FALSE) ; 


} 
break; 


// The painting function. This message is sent by Windows 
// whenever the screen needs updating. 
case WM_PAINT: 

i 

// Call OpenGL drawing code 

RenderScene() ; 


// Call function to swap the buffers 
SwapBuffers(hDC) ; 


// Validate the newly painted client area 
ValidateRect (hWnd,NULL) ; 


} 
break; 


default: // Passes it on if unprocessed 
return (DefWindowProc(hWnd, message, wParam, 1lParam)); 


return (QL); 


} 


Initializing the Rendering Context 
The first thing you do when the window is being created is retrieve the device context 
(remember, you hang on to it) and set the pixel format: 
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// Store the device context 
hDC = GetDC(hWnd) ; 


// Select the pixel format 
SetDCPixelFormat(hDC) ; 


Then you create the OpenGL rendering context and make it current: 


// Create the rendering context and make it current 
hRC = wglCreateContext(hDC) ; 
wglMakeCurrent(hDC, hRC); 


The last task you handle while processing the WM_CREATE message is creating a Windows 
timer for the window. You will use this shortly to affect the animation loop: 


// Create a timer that fires 30 times a second 
SetTimer(hWnd,33,1,NULL) ; 
break; 


At this point, the OpenGL rendering context has been created and associated with a 
window with a valid pixel format. From this point forward, all OpenGL rendering 
commands will be routed to this context and window. 


Shutting Down the Rendering Context 

When the window procedure receives the WM_DESTROY message, the OpenGL rendering 
context must be deleted. Before you delete the rendering context with the 
wglDeleteContext function, you must first call wglMakeCurrent again, but this time with 
NULL as the parameter for the OpenGL rendering context: 


// Deselect the current rendering context and delete it 
wglMakeCurrent(hDC, NULL) ; 
wglDeleteContext (hRC) ; 


Before deleting the rendering context, you should delete any display lists, texture objects, 
or other OpenGL-allocated memory. 


Other Windows Messages 

All that is required to enable OpenGL to render into a window is creating and destroying 
the OpenGL rendering context. However, to make your application well behaved, you 
need to follow some conventions with respect to message handling. For example, you 
need to set the viewport when the window changes size, by handling the WM_SIZE 
message: 


// Window is resized. 
case WM_SIZE: 
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// Call our function which modifies the clipping 
// volume and viewport 
ChangeSize(LOWORD(1Param) , HIWORD(1Param)) ; 
break; 


The processing that happens in response to the WM_SIZE message is the same as in the 
function you handed off to glutReshapeFunc in GLUT-based programs. The window proce- 
dure also receives two parameters: 1Param and wParam. The low word of 1Param is the new 
width of the window, and the high word is the height. 


This example uses the WM_TIMER message handler to do the idle processing. The process is 
not really idle, but the previous call to SetTimer causes the WM_TIMER message to be 
received on a fairly regular basis (fairly because the exact interval is not guaranteed). 


Other Windows messages handle things such as keyboard activity (WM_CHAR, WM_KEYDOWN), 
mouse movements (WM_MOUSEMOVE), and palette management. (We discuss these messages 
shortly.) 


The WM_PAINT Message 

The WM_PAINT message bears a closer examination. This message is sent to a window when- 
ever Windows needs to draw or redraw its contents. To tell Windows to redraw a window 
anyway, you invalidate the window with one function call in the WW_TIMER message 
handler: 


IdleFunction(); 
InvalidateRect (hWnd,NULL, FALSE) ; 


Here, IdleFunction updates the position of the square, and InvalidateRect tells Windows 
to redraw the window (now that the square has moved). 


Most Windows programming books show you a WM_PAINT message handler with the well- 
known BeginPaint/EndPaint function pairing. BeginPaint retrieves the device context so 
it can be used for GDI drawing, and EndPaint releases the context and validates the 
window. In our previous discussion of why you need the CS_OWNDC class style, we pointed 
out that using this function pairing is generally a bad idea for high-performance graphics 
applications. The following code shows roughly the equivalent functionality, without 
quite so much overhead: 


// The painting function. This message is sent by Windows 
// whenever the screen needs updating. 
case WM_PAINT: 

{ 

// Call OpenGL drawing code 

RenderScene(); 
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// Call function to swap the buffers 
SwapBuffers(hDC) ; 


// Validate the newly painted client area 
ValidateRect (hWnd, NULL) ; 


} 
break; 


Because this example has a device context (hDC), you don’t need to continually get and 
release it. We’ve mentioned the SwapBuffers function previously but not fully explained 
it. This function takes the device context as an argument and performs the buffer swap for 
double-buffered rendering. This is why you need the device context readily available when 
rendering. 


Notice that you must manually validate the window with the call to ValidateRect after 
rendering. Without the BeginPaint/EndPaint functionality in place, there is no way to tell 
Windows that you have finished drawing the window contents. One alternative to using 
WM_TIMER to invalidate the window (thus forcing a redraw) is to simply not validate the 
window. If the window procedure returns from a WM_PAINT message and the window is not 
validated, the operating system generates another WM_PAINT message. This chain reaction 
causes an endless stream of repaint messages. One problem with this approach to anima- 
tion is that it can leave little opportunity for other window messages to be processed. 
Although rendering might occur very quickly, the user might find it difficult or impossible 
to resize the window or use the menu, for example. 


Windows Palettes 


In Chapter 5, “Color, Materials, and Lighting: The Basics,” we discussed the various color 
modes available on the modern PC running Windows. Hardware-accelerated 3D graphics 
cards for the PC support 16-bit or higher color resolutions. If you drop down to 8-bit color 
(256 colors), you most likely are running Microsoft’s generic software implementation. 
Although this graphics mode is becoming less common, your application could still find 
itself running in such an environment. Not all 3D applications require hardware accelera- 
tion, and many users might not even care about hardware versus software rendering. 


Color Matching 

What happens when you try to draw a pixel of a particular color using the RGB values in 
glColor? If the PC graphics card is in 24-bit color mode, each pixel is displayed precisely 
in the color specified by the 24-bit value (three 8-bit intensities). In the 15- and 16-bit 
color modes, Windows passes the 24-bit color value to the display driver, which reduces 
the color to a 15- or 16-bit color value before displaying it. Internal color calculations due 
to lighting and texturing are usually (depending on the implementation) done at full 
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precision. Reducing a color’s precision from 24-bit to 16-bit results in some loss of visual 
fidelity but can be acceptable for many applications. 


On a Windows display with only 8 bits of color resolution (256 colors), Windows creates a 
palette of colors for the display device. A palette is a list of color values specified at full 
color. When an application needs to specify one of these colors, it does so by index rather 
than by specifying the exact color. In practice, the color entries in a palette can be arbi- 
trary and are often chosen to match a particular application’s needs. 


When Windows is running in a color mode that supports 256 colors, it would make sense 
if those colors were evenly distributed across RGB colorspace. (See the color cube example 
in Chapter 5.) Then all applications would have a relatively wide choice of colors, and 
when a color was selected, the nearest available color would be used. This is exactly the 
type of palette that OpenGL requires when running in a paletted color mode. 
Unfortunately, this arrangement is not always practical for other applications. 


Because the 256 colors in the palette for the device can be selected from more than 16 
million different colors, an application can substantially improve the quality of its graph- 
ics by carefully selecting those colors—and many do. For example, to produce a seascape, 
additional shades of blue might be needed. CAD and modeling applications can modify 
the palette to produce smooth shading of a surface of a particular single color. For 
example, the scene might require as many as 200 shades of gray to accurately render the 
image of a pipe’s cross-section. Thus, applications for the PC typically change the palette 
to meet their needs, resulting in near-photographic quality for many images and scenes. 
For 256-color bitmaps, the Windows .BMP format even has an array that’s 256 entries 
long, containing 24-bit RGB values specifying the palette for the stored image. 


An application can create a palette with the Windows CreatePalette function, identifying 
the palette by a handle of type HPALETTE. This function takes a logical palette structure 
(LOGPALETTE) that contains 256 entries, each specifying 8-bit values for red, green, and 
blue components. Before we examine palette creation, let’s look at how multitasked appli- 
cations can share the single system palette in 8-bit color mode. 


Palette Arbitration 


Windows multitasking allows many applications to be onscreen at once. If the hardware 
supports only 256 colors onscreen at once, all applications must share the same system 
palette. If one application changes the system palette, images in the other windows might 
have scrambled colors, producing some undesired psychedelic effects. To arbitrate palette 
usage among applications, Windows sends a set of messages. Applications are notified 
when another application has changed the system palette, and they are notified when 
their window has received focus and palette modification is allowed. 


When an application receives keyboard or mouse input focus, Windows sends a 
WM_QUERYNEWPALETTE message to the main window of the application. This message asks 
the application whether it wants to realize a new palette. Realizing a palette means the 
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application copies the palette entries from its private palette to the system palette. To do 
this, the application must first select the palette into the device context for the window 
being updated and then call RealizePalette. 


Another message sent by Windows for palette realization is WM_PALETTECHANGED. This 
message is sent to windows that can realize their palette but might not have the current 
focus. When this message is sent, you must also check the value of wParam. If wParam 
contains the handle to the current window receiving the message, then WM_ 
QUERYNEWPALETTE has already been processed, and the palette does not need to be 
realized again. Listing 13.3 shows the message handler for these two messages. 


LISTING 13.3 Message Handlers for Windows Palette Management 


FUTTTTTTTT TTT TTT TT TL 
// Windows is telling the application that it may modify 
// the system palette. This message in essence asks the 
// application for a new palette. 
case WM_QUERYNEWPALETTE: 
// If the palette was created. 
if (hPalette) 
{ 
int nRet; 


// Selects the palette into the current device context 
SelectPalette(hDC, hPalette, FALSE); 


// Map entries from the currently selected palette to 
// the system palette. The return value is the number 
// of palette entries modified. 

nRet = RealizePalette(hDC) ; 


// Repaint, forces remap of palette in current window 
InvalidateRect (hWnd,NULL, FALSE) ; 


return nRet; 


} 
break; 


TLTTTTTTTTT TTT ATT TTT A A TL 
// This window may set the palette, even though it is not the 
// currently active window. 
case WM_PALETTECHANGED: 
// Don't do anything if the palette does not exist or if 
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LISTING 13.3 Continued 


// this is the window that changed the palette. 
if((hPalette != NULL) && ((HWND)wParam != hWnd)) 
{ 
// Select the palette into the device context 
SelectPalette(hDC,hPalette, FALSE) ; 


// Map entries to system palette 
RealizePalette(hDC) ; 


// Remap the current colors to the newly realized palette 
UpdateColors(hDC) ; 
return Q; 


} 
break; 


A Windows palette is identified by a handle of type HPALETTE. The hPalette variable 
shown in Listing 13.3 is this type. Note that the value of hPalette is checked against NULL 
before either of these palette-realization messages is processed to check for a potential 
error. If the application is not running in 8-bit color mode, these messages are not posted 
to your application. 


Creating a Palette for OpenGL 


Unfortunately, palette considerations are a necessary evil if your application is to run on 
the 8-bit hardware that’s still widely in use. What do you do if your code is executing on a 
machine that supports only 256 colors? 


For an application such as image reproduction, we recommend selecting a range of colors 
that closely match the original colors. Selecting the best reduced palette for a given full- 
color image has been the subject of much study over the years and is well beyond the 
scope of this book. For OpenGL rendering under most circumstances, you want the widest 
possible range of colors for general-purpose use. The trick is to select the palette colors so 
that they’re evenly distributed throughout the color cube. Then, whenever a color not 
already in the palette is specified, Windows will select the nearest color in the color cube. 
As mentioned earlier, this arrangement is not ideal for some applications, but for OpenGL- 
rendered scenes, it is the best you can do. Unless the scene has substantial texture 
mapping with a wide variety of colors, the results are usually acceptable. 


The sample program GLPALETTE, shown in Figure 13.5, demonstrates the results. This 
program creates a spinning cube textured on each side with a familiar face. Run this 
program on your PC in both full-color (16-bit or higher) and 256-color mode. The effect 
can’t be accurately reproduced as a grayscale image in this book, but you can see that even 
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in 8-bit color mode, OpenGL is able to reproduce the image quite well, despite the limited 
range of colors available. 


SE ES eS 


Palette =D) 


a 


FIGURE 13.5 The Mona Lisa cube, quite recognizable even in 8-bit color mode. 


Do You Need a Palette? 

To determine whether your application needs a palette, you examine PIXELFORMATDE - 
SCRIPTOR returned by a call to DescribePixelFormat. Test the dwFlags member of the 
PIXELFORMATDESCRIPTOR structure, and if the bit value PFD_NEED_PALETTE is set, you need 
to create a palette for your application: 


DescribePixelFormat(hDC, nPixelFormat, sizeof (PIXELFORMATDESCRIPTOR), &pfd); 


// Does this pixel format require a palette? 
if(!(pfd.dwFlags & PFD_NEED PALETTE) ) 
return NULL; // Does not need a palette 
// Palette creation code 


The Palette’s Structure 

To create a palette, you must first allocate memory for a Windows LOGPALETTE structure. 
This structure is filled with the information that describes the palette and then is passed to 
the Win32 function CreatePalette. The LOGPALETTE structure is defined as follows: 


typedef struct tagLOGPALETTE { // lgpl 
WORD palVersion; 
WORD palNumEntries; 
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PALETTEENTRY palPalEntry[1]; 
} LOGPALETTE; 


The first two members are the palette header and contain the palette version (always set to 
0x300) and number of color entries (256 for 8-bit modes). Each entry is then defined as a 
PALETTEENTRY structure that contains the RGB components of the color entry. Additional 
entries are located at the end of the structure in memory. 


The following code allocates space for the logical palette: 


LOGPALETTE *pPal; // Pointer to memory for logical palette 


// Allocate space for a logical palette structure plus all the palette 
// entries 
pPal = (LOGPALETTE*)malloc(sizeof(LOGPALETTE) + nColors*sizeof (PALETTEENTRY) ) ; 


Here, nColors specifies the number of colors to place in the palette, which for our 
purposes is always 256. 


Each entry in the palette, then, is a PALETTEENTRY structure, which is defined as follows: 


typedef struct tagPALETTEENTRY { // pe 
BYTE peRed; 
BYTE peGreen; 
BYTE peBlue; 
BYTE peFlags; 
} PALETTEENTRY; 


The peRed, peGreen, and peBlue members specify an 8-bit value that represents the relative 
intensities of each color component. In this way, each of the 256 palette entries contains a 
24-color definition. The peFlags member describes advanced use of the palette entries. For 
OpenGL purposes, you can just set it to NULL. 


The 3-3-2 Palette 

Now comes the tricky part: Not only must the 256 palette entries be spread evenly 
throughout the RGB color cube, but also they must be in a certain order. It is this order 
that enables OpenGL to find the color it needs or the closest available color in the palette. 
In 8-bit color mode, you have 3 bits each for red and green color components and 2 bits 
for the blue component. This is commonly referred to as a 3-3-2 palette. So the RGB color 
cube measures 8x8x3 along the red, green, and blue axes, respectively. 


To find the color needed in the palette, an 8-8-8 color reference (the 24-bit color mode 
setup) is scaled to a 3-3-2 color value. This 8-bit value is then the index into the palette 
array. The red intensities of 0 to 7 in the 3-3-2 palette must correspond to the intensities 0 
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to 255 in the 8-8-8 palette. Figure 13.6 illustrates how the red, green, and blue compo- 
nents are combined to make the palette index. 


8-bit Palette Index 
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FIGURE 13.6 Sample of 3-3-2 palette packing. 


When you build the palette, you loop through all values from 0 to 255. You then decom- 
pose the index into the red, green, and blue intensities represented by these values (in 
terms of the 3-3-2 palette). Each component is multiplied by 255 and divided by the 
maximum value represented, which has the effect of smoothly stepping the intensities 
from 0 to 7 for red and green and from 0 to 3 for the blue. Table 13.2 shows some sample 
palette entries to demonstrate component calculation. 


TABLE 13.2 A Few Sample Palette Entries for a 3-3-2 Palette 


Palette Binary 
Entry (BG R) 

0 00 000 000 
1 00 000 001 
2 00 000 010 
3 00 000 011 
9 00 001 001 
10 00 001 010 
137 10 001 001 
138 10 001 010 
255 11111111 


Building the Palette 


Blue 
Component 


0 


ooococo 


2*255/3 
2*255/7 
3*255/3 


Green 
Component 
0 

0 

0 

0 
1*255/7 
1*255/7 
1*255/7 
1*255/7 
7*255/7 


Red 
Component 
0 
1*255/7 
2*255/7 
3*255/7 
1*255/7 
2*255/7 
1*255/7 
2*255/3 
7*255/7 


The 3-3-2 palette is actually specified by PIXELFORMATDESCRIPTOR returned by 
DescribePixelFormat. The members cRedBits, cGreenBits, and cBlueBits specify 3, 3, 
and 2, respectively, for the number of bits that can represent each component. 
Furthermore, the cRedShift, cGreenShift, and cBlueShift values specify how much to 
shift the respective component value to the left (in this case, 0, 3, and 6 for red, green, 
and blue shifts). These sets of values compose the palette index (see Figure 13.6). 


The code in Listing 13.4 creates a palette if needed and returns its handle. This function 
makes use of the component bit counts and shift information in PIXELFORMATDESCRIPTOR 
to accommodate any subsequent palette requirements, such as a 2-2-2 palette. 


675 


€L 


676 


CAHPTER 13 Wiggle: OpenGL on Windows 


LISTING 13.4 Function to Create a Palette for OpenGL 


// If necessary, creates a 3-3-2 palette for the device context listed. 
HPALETTE GetOpenGLPalette(HDC hDC) 
{ 
HPALETTE hRetPal = NULL; // Handle to palette to be created 
PIXELFORMATDESCRIPTOR pfd; // Pixel format descriptor 


LOGPALETTE *pPal; // Pointer to memory for logical palette 
int nPixelFormat; // Pixel format index 

int nColors; // Number of entries in palette 

int i; // Counting variable 


BYTE RedRange,GreenRange, BlueRange; 
// Range for each color entry (7,7,and 3) 


// Get the pixel format index and retrieve the pixel format description 
nPixelFormat = GetPixelFormat(hDC) ; 
DescribePixelFormat(hDC, nPixelFormat, 

sizeof (PIXELFORMATDESCRIPTOR), &pfd); 


// Does this pixel format require a palette? If not, do not create a 
// palette and just return NULL 
if(!(pfd.dwFlags & PFD_NEED_PALETTE) ) 

return NULL; 


// Number of entries in palette. 8 bits yields 256 entries 
nColors = 1 << pfd.cColorBits; 


// Allocate space for a logical palette structure plus all the palette 
// entries 
pPal = (LOGPALETTE*)malloc(sizeof(LOGPALETTE) + 
nColors*sizeof (PALETTEENTRY) ) ; 


// Fill in palette header 
pPal->palVersion = 0x300; // Windows 3.0 
pPal->palNumEntries = nColors; // table size 


// Build mask of all 1s. This creates a number represented by having 

// the low order x bits set, where x = pfd.cRedBits, pfd.cGreenBits, and 
// pfd.cBlueBits. 

RedRange = (1 << pfd.cRedBits) -1; // 7 for 3-3-2 palettes 
GreenRange = (1 << pfd.cGreenBits) - 1; // 7 for 3-3-2 palettes 
BlueRange = (1 << pfd.cBlueBits) -1; // 3 for 3-3-2 palettes 
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LISTING 13.4 Continued 


// Loop through all the palette entries 
for(i = 0; i < nColors; i++) 
{ 
// Fill in the 8-bit equivalents for each component 
pPal->palPalEntry[i].peRed = (i >> pfd.cRedShift) & RedRange; 
pPal->palPalEntry[i].peRed = (unsigned char) ( 
(double) pPal->palPalEntry[i].peRed * 255.0 / RedRange) ; 


pPal->palPalEntry[i].peGreen = (i >> pfd.cGreenShift) & GreenRange; 
pPal->palPalEntry[i].peGreen = (unsigned char) ( 
(double)pPal->palPalEntry[i].peGreen * 255. /GreenRange) ; 


pPal->palPalEntry[i].peBlue = (i >> pfd.cBlueShift) & BlueRange; 
pPal->palPalEntry[i].peBlue = (unsigned char) ( 
(double) pPal->palPalEntry[i].peBlue * 255.0 / BlueRange); 


pPal->palPalEntry[i].peFlags = (unsigned char) NULL; 
} 


// Create the palette 
hRetPal = CreatePalette(pPal) ; 


// Go ahead and select and realize the palette for this device context 
SelectPalette(hDC,hRetPal, FALSE) ; 
RealizePalette(hDC) ; 


// Free the memory used for the logical palette structure 
free(pPal) ; 


// Return the handle to the new palette 
return hRetPal; 


} 


Palette Creation and Disposal 

The Windows palette should be created and realized before the OpenGL rendering context 
is created or made current. The function in Listing 13.4 requires only the device context 
after the pixel format has been set. It then returns a handle to a palette if one is needed. 
Listing 13.5 shows the sequence of operations when the window is created and destroyed. 
This listing is similar to code presented previously for the creation and destruction of the 
rendering context, but now it also takes into account the possible existence of a palette. 
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LISTING 13.5 Creating and Destroying a Palette 


// Window creation, set up for OpenGL 
case WM_CREATE: 

// Store the device context 

hDC = GetDC(hWnd) ; 


// Select the pixel format 
SetDCPixelFormat(hDC) ; 


// Create the palette if needed 
hPalette = GetOpenGLPalette(hDC) ; 


// Create the rendering context and make it current 
hRC = wglCreateContext(hDC) ; 

wglMakeCurrent(hDC, hRC); 

break; 


// Window is being destroyed, clean up 

case WM_DESTROY: 
// Deselect the current rendering context and delete it 
wglMakeCurrent(hDC, NULL) ; 
wglDeleteContext(hRC) ; 


// If a palette was created, destroy it here 
if(hPalette != NULL) 
DeleteObject(hPalette) ; 


// Tell the application to terminate after the window 
// is gone. 

PostQuitMessage(Q) ; 

break; 


Some Restrictions Apply 

Not all your 256 palette entries are actually mapped to the system palette. Windows 
reserves 20 entries for static system colors that include the standard 16 VGA/EGA colors. 
This protects the standard Windows components (title bars, buttons, and so on) from 
alteration whenever an application changes the system palette. When your application 
realizes its palette, these 20 colors are not overwritten. Fortunately, some of these colors 
already exist or are closely matched in the 3-3-2 palette. Those that don’t are matched 
closely enough that you shouldn’t be able to tell the difference for most purposes. 


OpenGL and Windows Fonts 


We need to add one last important note about paletted rendering with OpenGL. The 
methods presented here enable you to specify colors as full RGBA components, and only 
at the point of rasterization are they converted to the nearest available palette entry. 
OpenGL does have an older and obsolete rendering mode called color index mode in which 
you can specify colors as actual palette entry indexes. Color index mode does not support 
modern features such as texture mapping and is not hardware accelerated on the PC (or 
the Mac, or Linux...). For these reasons, color index mode should be considered dead and 
is not covered by this text. 


OpenGL and Windows Fonts 


One of the nicer features of Windows is its support for TrueType fonts. These fonts have 
been native to Windows since before Windows became a 32-bit operating system. 
TrueType fonts enhance text appearance because they are device independent and can be 
easily scaled while still keeping a smooth shape. TrueType fonts are vector fonts, not 
bitmap fonts. What this means is that the character definitions consist of a series of point 
and curve definitions. When a character is scaled, the overall shape and appearance 
remain smooth. 


Textual output is a part of nearly any Windows application, and 3D applications are no 
exception. Microsoft provided support for TrueType fonts in OpenGL with two new wiggle 
functions. You can use the first, wglUseFontOutlines, to create 3D font models that can be 
used to create 3D text effects. The second, wglUseFontBitmaps, creates a series of font 
character bitmaps that can be used for 2D text output in a double-buffered OpenGL 
window. 


3D Fonts and Text 


The wglUseFontOutlines function takes a handle to a device context. It uses the TrueType 
font currently selected into that device context to create a set of display lists for that font. 
Each display list renders just one character from the font. Listing 13.6 shows the SetupRC 
function from the sample program TEXT3D, where you can see the entire process of creat- 
ing a font, selecting it into the device context, creating the display lists, and finally, delet- 
ing the (Windows) font. 


LISTING 13.6 Creating a Set of 3D Characters 


void SetupRC(HDC hDC) 
{ 
// Set up the font characteristics 
HFONT hFont; 
GLYPHMETRICSFLOAT agmf[128]; // Throw away 
LOGFONT logfont; 
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LISTING 13.6 Continued 


logfont.1fHeight = -10; 

logfont.1fWidth = ; 

logfont.1fEscapement = Q; 
logfont.1fOrientation = 0; 

logfont.1fWeight = FW_BOLD; 

logfont.1fItalic = FALSE; 
logfont.1fUnderline = FALSE; 
logfont.1fStrikeOut = FALSE; 
logfont.1fCharSet = ANSI_CHARSET; 
logfont.1fOutPrecision = OUT_DEFAULT_PRECIS; 
logfont.1fClipPrecision = CLIP_DEFAULT_PRECIS; 
logfont.1fQuality = DEFAULT_QUALITY; 
logfont.1fPitchAndFamily = DEFAULT_PITCH; 
strepy(logfont.1fFaceName, "Arial") ; 


// Create the font and display list 
hFont = CreateFontIndirect(&logfont) ; 
SelectObject (hDC, hFont); 


// Create display lists for glyphs ® through 128 with @.1 extrusion 

// and default deviation. The display list numbering starts at 1000 

// (it could be any number). 

nFontList = glGenLists(128) ; 

wglUseFontOutlines(hDC, @, 128, nFontList, 0.0f, 0.5f, 
WGL_FONT_POLYGONS, agmf) ; 


DeleteObject(hFont) ; 


The function call to wg1UseFontOutlines is the key function call to create your 3D charac- 
ter set: 


wglUseFontOutlines(hDC, ®, 128, nFontList, 0.0f, 0.5f, 
WGL_FONT_POLYGONS, agmf) ; 


The first parameter is the handle to the device context where the desired font has been 
selected. The next two parameters specify the range of characters (called glyphs) in the font 
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to use. In this case, you use the 1st through 127th character. (The indexes are zero based.) 
The third parameter, nFontList, is the beginning of the range of display lists created previ- 
ously. It is important to allocate your display list space before using either of the WGL font 
functions. The next parameter is the chordal deviation. Think of it as specifying how 
smooth you want the font to appear, with 0.0 being the most smooth. 


The 0.5f is the extrusion of the character set. The 3D characters are defined to lay in the 
xy plane. The extrusion determines how far along the z-axis the characters extend. 
WGL_FONT_POLYGONS tells OpenGL to create the characters out of triangles and quads so 
that they are solid. When this information is specified, normals are also calculated and 
supplied for each letter. Only one other value is valid for this parameter: WGL_FONT_LINES. 
It produces a wireframe version of the character set and does not generate normals. 


The last argument is an array of type GLYPHMETRICSFLOAT, which is defined as follows: 
typedef struct _GLYPHMETRICSFLOAT { 


FLOAT gmfBlackBoxx; // Extent of character cell in x direction 
FLOAT gmfBlackBoxY; // Extent of character cell in y direction 
POINTFLOAT gmfptGlyphOrigin; // Origin of character cell 

FLOAT gmfCellIncx; // Horizontal distance to origin of next cell 
FLOAT gmfCellIncy; // Vertical distance to origin of next cell 


}; GLYPHMETRICSFLOAT 


Windows fills in this array according to the selected font’s characteristics. These values can 
be useful when you want to determine the size of a string rendered with 3D characters. 


Rendering 3D Text 

When the display list for each character is called, it renders the character and advances the 
current position to the right (positive x direction) by the width of the character cell. This 
is like calling gl1Translate after each character, with the translation in the positive x direc- 
tion. You can use the g1CallLists function in conjunction with glListBase to treat a 
character array (a string) as an array of offsets from the first display list in the font. A 
simple text output method is shown in Listing 13.7. The output from the TEXT3D 
program appears in Figure 13.7. 


LISTING 13.7 Rendering a 3D Text String 


void RenderScene(void) 


{ 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 


// Blue 3D text 
glColor3ub(@, @, 255); 
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LISTING 13.7 Continued 


glPushMatrix(); 

glListBase(nFontList) ; 

glCallLists (6, GL_UNSIGNED BYTE, "OpenGL"); 
glPopMatrix() ; 

} 


FIGURE 13.7 Sample 3D text in OpenGL. 


2D Fonts and Text 


The wglUseFontBitmaps function is similar to its 3D counterpart. This function does not 
extrude the bitmaps into 3D, however, but instead creates a set of bitmap images of the 
glyphs in the font. You output images to the screen using the bitmap functions discussed 
in Chapter 7, “Imaging with OpenGL.” Each character rendered advances the raster posi- 
tion to the right in a similar manner to the 3D text. 


Listing 3.8 shows the code to set up the coordinate system for the window (ChangeSize 
function), create the bitmap font (SetupRC function), and finally render some text 
(RenderScene function). The output from the TEXT2D sample program is shown in 
Figure 13.8. 


LISTING 3.8 Creating and Using a 2D Font 


PUTTTLLT TTT TTT LTT TATTLE 
// Window has changed size. Reset to match window coordinates 
void ChangeSize(GLsizei w, GLsizei h) 

{ 

GLfloat nRange = 100.0f; 

GLfloat fAspect; 
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LISTING 13.8 Continued 
// Prevent a divide by zero 
if ( == Q) 
h=1; 


fAspect = (GLfloat)w/(GLfloat)h; 


// Set Viewport to window dimensions 
glViewport(®, ®, w, h); 
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glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 


gluOrtho2D(0,400, 400, 0); 


// Viewing transformation 
glMatrixMode(GL_MODELVIEW) ; 
glLoadIdentity(); 

} 


FLTTTTTTT TTT TTT TTA 
// Setup. Use a Windows font to create the bitmaps 
void SetupRC(HDC hDC) 

{ 

// Setup the Font characteristics 

HFONT hFont; 

LOGFONT logfont; 


logfont.1fHeight = -20; 

logfont.1fWidth = 0; 

logfont.1fEscapement = Q; 
logfont.1fOrientation = Q; 

logfont.1fWeight = FW_BOLD; 

logfont.1fItalic = FALSE; 
logfont.1fUnderline = FALSE; 
logfont.1fStrikeOut = FALSE; 
logfont.1fCharSet = ANSI_CHARSET; 
logfont.1fOutPrecision = OUT_DEFAULT_PRECIS; 
logfont.1fClipPrecision = CLIP_DEFAULT_PRECIS; 
logfont.1fQuality = DEFAULT_QUALITY; 
logfont.1fPitchAndFamily = DEFAULT_PITCH; 
strepy(logfont.1fFaceName, "Arial") ; 
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LISTING 13.8 Continued 
// Create the font and display list 
hFont = CreateFontIndirect (&logfont) ; 
SelectObject (hDC, hFont); 


//Create display lists for glyphs @ through 128 
nFontList = glGenLists(128) ; 
wglUseFontBitmaps(hDC, ®, 128, nFontList); 


DeleteObject(hFont) ; // Don't need original font anymore 


// Black Background 
glClearColor(@.0f, 0.0f, 0.0f, 1.0f ); 
} 


LTLTTT TTT TTT TTT 
// Draw everything (just the text) 
void RenderScene(void) 


{ 
glClear(GL_COLOR_BUFFER_BIT) ; 


// Blue 3D Text - Note color is set before the raster position 
glColor3f(1.0f, 1.0f, 1.0f); 

glRasterPos2i(@, 200); 

glListBase(nFontList) ; 

glCallLists (13, GL_UNSIGNED_BYTE, “OpenGL Rocks!"); 


} 


Note that wglUseFontBitmaps is a much simpler function. It requires only the device 
context handle, the beginning and last characters, and the first display list name to be 
used: 


wglUseFontBitmaps(hDC, 0, 128, nFontList); 
Because bitmap fonts are created based on the actual font and map directly to pixels on 


the screen, the 1fHeight member of the LOGFONT structure is used exactly in the same way 
it is for GDI font rasterization. 


Full-Screen Rendering 
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OpenGL Rocks! 


FIGURE 13.8 Output from the TEXT2D sample program. 


Full-Screen Rendering 


With OpenGL becoming popular among PC game developers, a common question is 
“How do I do full-screen rendering with OpenGL?” The truth is, if you’ve read this 
chapter, you already know how to do full-screen rendering with OpenGL—it’s just like 
rendering into any other window! The real question is “How do I create a window that 
takes up the entire screen and has no borders?” Once you do this, rendering into this 
window is no different from rendering into any other window in any other sample in this 
book. 


Even though this issue isn’t strictly related to OpenGL, it is of enough interest to a wide 
number of our readers that we give this topic some coverage here. 


Creating a Frameless Window 

The first task is to create a window that has no border or caption. This procedure is quite 
simple. Following is the window creation code from the GLRECT sample program. We’ve 
made one small change by making the window style WS_POPUP instead of WS_ 
OVERLAPPEDWINDOW: 


// Create the main application window 
hWnd = CreateWindow(lpszAppName, 
lpszAppName, 
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// OpenGL requires WS_CLIPCHILDREN and WS_CLIPSIBLINGS 
WS_POPUP | WS _CLIPCHILDREN | WS_CLIPSIBLINGS, 


// Window position and size 
100, 100, 

250, 250, 

NULL, 

NULL, 

hInstance, 

NULL) ; 


The result of this change is shown in Figure 13.9. 


FIGURE 13.9 A window with no caption or border. 


As you can see, without the proper style settings, the window has neither a caption nor a 
border of any kind. Don’t forget to take into account that now the window no longer has 
a close button on it. The user will have to press Alt+F4 to close the window and exit the 
program. Most user-friendly programs watch for a keystroke such as the Esc key or Q to 
terminate the program. 


Creating a Full-Screen Window 


Creating a window the size of the screen is almost as trivial as creating a window with no 
caption or border. The parameters of the CreateWindow function allow you to specify 
where onscreen the upper-left corner of the window will be positioned and the width and 
height of the window. To create a full-screen window, you always use (0,0) as the upper- 
left corner. The only trick would be determining what size the desktop is so you know 
how wide and high to make the window. You can easily determine this information by 
using the Windows function GetDeviceCaps. 


Listing 13.9 shows the new WinMain function from GLRECT, which is now the new sample 
FSCREEN. To use GetDeviceCaps, you need a device context handle. Because you are in the 
process of creating the main window, you need to use the device context from the desktop 
window. 


Full-Screen Rendering 


LISTING 13.9 Creating a Full-Screen Window 


// Entry point of all Windows programs 
int APIENTRY WinMain( HINSTANCE hInstance, 
HINSTANCE hPreviInstance, 


LPSTR lpCmdLine, 
int nCmdShow) 
{ 
MSG msg; // Windows message structure 
WNDCLASS we; // Windows class structure 
HWND hWnd; // Storage for window handle 
HWND hDesktopWnd; // Storage for desktop window handle 
HDC hDesktopDC; // Storage for desktop window device context 
int nScreenX, nScreenY; // Screen Dimensions 


// Register Window style 


we.style = CS_HREDRAW | CS_VREDRAW |} CS_OWNDC; 
we. 1pfnWndProc = (WNDPROC) WndProc; 

we.cbClsExtra = Q; 

we.cbWndExtra = Q; 

we. .hInstance = hInstance; 

we. hIcon = NULL; 

we.hCursor = LoadCursor(NULL, IDC_ARROW) ; 


// No need for background brush for OpenGL window 


we. hbrBackground = NULL; 
we. 1pszMenuName = NULL; 
we.lpszClassName = lpszAppName; 


// Register the window class 
if (RegisterClass(&wc) == Q) 
return FALSE; 


// Get the Window handle and Device context to the desktop 
hDesktopWnd = GetDesktopWindow( ) ; 
hDesktopDC = GetDC(hDesktopWndq) ; 


// Get the screen size 
nScreenX = GetDeviceCaps(hDesktopDC, HORZRES) ; 
nScreenY = GetDeviceCaps(hDesktopDC, VERTRES) ; 


// Release the desktop device context 
ReleaseDC(hDesktopWnd, hDesktopDC) ; 
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LISTING 13.9 Continued 


// Create the main application window 
hWnd = CreateWindow(lpszAppName, 
lpszAppName, 
// OpenGL requires WS_CLIPCHILDREN and WS_CLIPSIBLINGS 
WS_POPUP | WS_CLIPCHILDREN |} WS_CLIPSIBLINGS, 
// Window position and size 
®, 0, 
nScreenX, nScreeny, 
NULL, 
NULL, 
hInstance, 
NULL) ; 


// If window was not created, quit 
if (hWnd == NULL) 
return FALSE; 


// Display the window 
ShowWindow( hWnd , SW_SHOW) ; 
UpdateWindow( hWnd) ; 


// Process application messages until the application closes 
while( GetMessage(&msg, NULL, 0, Q)) 

{ 

TranslateMessage(&msg) ; 

DispatchMessage (&msg) ; 

; 


return msg.wParam; 


} 


The key code here is the lines that get the desktop window handle and device context. 
The device context can then be used to obtain the screen’s horizontal and vertical resolu- 
tion: 


hDesktopWnd = GetDesktopWindow() ; 
hDesktopDC = GetDC(hDesktopWnd) ; 


// Get the screen size 
nScreenX = GetDeviceCaps(hDesktopDC, HORZRES) ; 
nScreenY = GetDeviceCaps(hDesktopDC, VERTRES); 


Multithreaded Rendering 


// Release the desktop device context 
ReleaseDC(hDesktopWnd, hDesktopDC) ; 


If your system has multiple monitors, you should note that the values returned here 
would be for the primary display device. You might also be tempted to force the window 
to be a topmost window (using the WS_EX_TOPMOST window style). However, doing so 
makes it possible for your window to lose focus but remain on top of other active 
windows. This may confuse the user when the program stops responding to keyboard 
strokes. 


You may also want to take a look at the Win32 function ChangeDisplaySettings in your 
Windows SDK documentation. This function allows you to dynamically change the 
desktop size at runtime and restore it when your application terminates. This capability 
may be desirable if you want to have a full-screen window but at a lower or higher display 
resolution than the default. If you do change the desktop settings, you must not create the 
rendering window or set the pixelformat until after the desktop settings have changed. 
OpenGL rendering contexts created under one environment (desktop settings) are not 
likely to be valid in another. 


Multithreaded Rendering 


A powerful feature of the Win32 API is multithreading. The topic of threading is beyond 
the scope of a book on computer graphics. Basically, a thread is the unit of execution for 
an application. Most programs execute instructions sequentially from the start of the 
program until the program terminates. A thread of execution is the path through the 
machine code that the CPU traverses as it fetches and executes instructions. By creating 
multiple threads using the Win32 API, you can create multiple paths through your source 
code that are followed simultaneously. 


Think of multithreading as being able to call two functions at the same time and then 
having them executed simultaneously. Of course, the CPU cannot actually execute two 
code paths simultaneously, so it switches between threads during normal program flow 
much the same way a multitasking operating system switches between tasks. 


A program carefully designed for multithreaded execution can outperform a single- 
threaded application in many circumstances. On a single processor machine, one thread 
can service I/O requests, for example, while another handles the GUI. On a multiprocessor 
machine employing Symmetric Multi-Processing (SMP), more than one CPU can actually 
execute your program simultaneously. Note, however, that SMP processing is not 
supported by older versions of Windows (95/98/ME). 


Multithreading requires careful planning and usually causes applications to run more 
slowly or inefficiently when used improperly on a single CPU system. In addition, if a 
program is not thoroughly tested, it might never fail on a single CPU machine but have 
new bugs manifest on a machine with multiple processors. 
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Some OpenGL implementations take advantage of a multiprocessor system. If, for 
example, the transformation and lighting units of the OpenGL pipeline are not hardware 
accelerated, a driver can create another thread so that these calculations are performed by 
one CPU while another CPU feeds the transformed data to the rasterizer. 


You might think that using two threads to do your OpenGL rendering would speed up 
your rendering as well. You could perhaps have one thread draw the background objects 
in a scene while another thread draws the more dynamic elements. This configuration is 
almost always a bad idea. Although you can create two OpenGL rendering contexts for 
two different threads, most drivers fail if you try to render with both of them in the same 
window. Technically, this multithreading should be possible, and the Microsoft generic 
implementation will succeed if you try it, as might many hardware implementations. In 
the real world, the extra work you place on the driver with two contexts trying to share 
the same framebuffer will most likely outweigh any performance benefit you hope to gain 
from using multiple threads. 


Multithreading can benefit your OpenGL rendering on a multiprocessor system or even on 
a single processor system in at least two ways. In the first scenario, you have two different 
windows, each with its own rendering context and thread of execution. This case could 
still stress some drivers (some of the low-end game boards are stressed just by two applica- 
tions using OpenGL simultaneously!), but many professional OpenGL implementations 
can handle it quite well. 


The second example is if you are writing a game or a real-time simulation. You can have a 
worker thread perform physics calculations or artificial intelligence or handle player inter- 
action while another thread does the OpenGL rendering. This scenario requires careful 
sharing of data between threads but can provide a substantial performance boost on a 
dual-processor machine, and even a single-processor machine can improve the responsive- 
ness of your program. Although we’ve made the disclaimer that multithreaded program- 
ming is outside the scope of this book, we present for your use the sample program 
RTHREAD included on the CD for your examination, which creates and uses a rendering 
thread. This program also demonstrates the use of the OpenGL WGL extensions. 


OpenGL and WGL Extensions 


On the Windows platform, you do not have direct access to the OpenGL driver. All 
OpenGL function calls are routed through the openg132.d11 system file. Because this DLL 
understands only OpenGL 1.1 entrypoints (function names), you must have a mechanism 
to get a pointer to an OpenGL function supported directly by the driver. Fortunately, the 
Windows OpenGL implementation has a function named wglGetProcAddress that allows 
you to retrieve a pointer to an OpenGL function supported by the driver, but not necessar- 
ily natively supported by openg132.d11: 


PROC wglGetProcAddress(LPSTR lpszProc) ; 


OpenGL and WGL Extensions 


This function takes the name of an OpenGL function or extension and returns a function 
pointer that you can use to call that function directly. For this to work, you must know 
the function prototype for the function so you can create a pointer to it and subsequently 
call the function. 


OpenGL extensions (and post-version 1.1 features) come in two flavors. Some are simply 
new constants and enumerants recognized by a vendor’s hardware driver. Others require 
that you call new functions added to the API. The number of extensions is extensive, espe- 
cially when you add in the newer OpenGL core functionality and vendor-specific exten- 
sions. Complete coverage of all OpenGL extensions would require an entire book in itself 
(if not an encyclopedia!). You can find a registry of extensions on the Internet and among 
the Web sites listed in Appendix A, “Further Reading.” 


Fortunately, the following two header files give you programmatic access to most OpenGL 
extensions: 


#include <wglext.h> 
#include <glext.h> 


These files can be found at the OpenGL extension registry Web site, but they are also 
maintained by most graphics card vendors (see their developer support Web sites), and the 
latest version as of this book’s printing is included in the \common source code directory on 
the CD. The wglext.h header contains a number of extensions that are Windows specific, 
and the glext.h header contains both standard OpenGL extensions and many vendor- 
specific OpenGL extensions. 


Simple Extensions 


Because this book covers known OpenGL features up to version 2.0, you may have already 
discovered that many of the sample programs in this book use these extensions for 
Windows builds of the sample code found in previous chapters. For example, in Chapter 
9, “Texture Mapping: Beyond the Basics,” we showed you how to add specular highlights 
to textured geometry using OpenGL’s separate specular color with the following function 
call: 


glLightModeli(GL_LIGHT_MODEL_COLOR_CONTROL, GL_SEPARATE_SPECULAR_COLOR) ; 


However, this capability is not present in OpenGL 1.1, and neither the 
GL_LIGHT_MODEL_COLOR_CONTROL or GL_SEPARATE_SPECULAR_COLOR constants are defined in 
the Windows version of gl.h. They are, however, found in glext.h, and this file is already 
included automatically in all the samples in this book via the OpenGLSB.h header file. The 
glLightModeli function, on the other hand, has been around since OpenGL 1.0. These 
kinds of simple extensions simply pass new tokens to existing entrypoints (functions) and 
require only that you have the constants defined and know that the extension or feature 
is supported by the hardware. 
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Even if the OpenGL version is still reported as 1.1, this capability may still be included in 
the driver. This feature was originally an extension that was later promoted to the OpenGL 
core functionality. You can check for this and other easy-to-access extensions (no function 
pointers needed) quickly by using the following G1Tools function: 


bool gltIsExtSupported(const char *szExtension) ; 


In the case of separate specular color, you might just code something like this: 


if (gltIsExtSupported(GL_EXT_separate_specular_color) ) 
RenderOnce(); 

else 
UseMultiPassTechnique() ; 


Here, you call the RenderOnce function if the extension (or feature) is supported and the 
UserMultiPassTechnique function to render an alternate (drawn twice and blended 
together) and slower way to achieve the same effect. 


Using New Entrypoints 


A more complex extension example comes from the IMAGING sample program in 
Chapter 7. In this case, the optional imaging subset is not only missing from the Windows 
version of gl.h, but is optional in all subsequent versions of OpenGL as well. This is an 
example of the type of feature that either has to be there, or there is no point in continu- 
ing. Thus, you first check for the presence of the imaging subset by checking for its exten- 
sion string: 


// Check for imaging subset, must be done after window 
// is created or there won't be an OpenGL context to query 
if (gltIsExtSupported("GL_ARB_imaging") == Q) 

{ 

printf("Imaging subset not supported\r\n"); 

return 0; 


} 


The function prototype typedefs for the functions used are found in glext.h, and you use 
them to create function pointers to each of the functions you want to call. On the 
Macintosh platform, the standard system headers already contain these functions: 


#ifndef _ APPLE__ 
// These typdefs are found in glext.h 


PFNGLHISTOGRAMPROC glHistogram = NULL; 
PFNGLGETHISTOGRAMPROC glGetHistogram = NULL; 
PFNGLCOLORTABLEPROC glColorTable = NULL; 


PFNGLCONVOLUTIONFILTER2DPROC glConvolutionFilter2D = NULL; 
#endif 


OpenGL and WGL Extensions 


Now you use the glTools function g1tGetExtensionPointer to retrieve the function 
pointer to the function in question. This function is simply a portability wrapper for 
wglGetProcAddress on Windows and an admittedly more complex method on the Apple 
of getting the function pointers: 


#ifndef _ APPLE__ 

glHistogram = gltGetExtensionPointer("glHistogram") ; 

glGetHistogram = gltGetExtensionPointer("“glGetHistogram") ; 

glColorTable = gltGetExtensionPointer(*glColorTable"); 
glConvolutionFilter2D = gltGetExtensionPointer("glConvolutionFilter2D") ; 
#endif 


Then you simply use the extension as if it were a normally supported part of the API: 


// Start collecting histogram data, 256 luminance values 
glHistogram(GL_HISTOGRAM, 256, GL_LUMINANCE, GL_FALSE) ; 
glEnable(GL_HISTOGRAW) ; 


WGL Extensions 


Several Windows-specific WGL extensions are also available—for example, the swap inter- 
val extension introduced in Chapter 2. You access the WGL extensions’ entrypoints in the 
same manner as the other extensions—using the wglGetProcAddress function. There is, 
however, an important exception. Typically, among the many WGL extensions, only two 
are advertised by using glGetString(GL_EXTENSIONS). They are the previously mentioned 
swap interval extension and the WGL_ARB_extensions_string extension. This extension 
provides yet another entrypoint that is used exclusively to query for the WGL extensions. 
The ARB extensions string function is prototyped as follows: 


const char *wglGetExtensionsStringARB(HDC hdc) ; 


This function retrieves the list of WGL extensions in the same manner you previously 
would have used glGetString. Using the wglext.h header file, you can retrieve a pointer 
to this function like this: 


PFNWGLGETEXTENSIONSSTRINGARBPROC *wglGetExtensionsStringARB; 
wglGetExtensionsStringARB = (PFNWGLGETEXTENSIONSSTRINGARBPROC) 
wglGetProcAddress("wglGetExtensionsStringARB") ; 


glGetString returns the WGL_ARB_extensions_string identifier, but often developers skip 
this check and simply look for the entrypoint, as shown in the preceding code fragment. 
This approach is generally safe with most OpenGL extensions, but you should realize that 
this is, strictly speaking, “coloring outside the lines.” Some vendors export extensions on 
an “experimental” basis, and these extensions may not be officially supported, or the 
functions may not function properly if you skip the extension string check. Also, more 
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than one extension may use the same function or functions. Testing only for function 
availability provides no information on the availability of the specific extension or exten- 
sions that are supported. 


Extended Pixel Formats 

Perhaps one of the most important WGL extensions available for Windows is the 
WGL_ARB_pixel_format extension. This extension provides a mechanism that allows you to 
check for and select pixelformat features that did not exist when PIXELFORMATDESCRIPTOR 
was first created. For example, if your driver supports multisampled rendering (for full- 
scene antialiasing, for example), there is no way to select a pixelformat with this support 
using the old PIXELFORMATDESCRIPTOR fields. If this extension is supported, the driver 
exports the following functions: 


BOOL wglGetPixelFormatAttribivARB(HDC hdc, GLint iPixelFormat, 
GLint iLayerPlane, GLuint nAttributes, 
const GLint *piAttributes, GLint *piValues) ; 


BOOL wglGetPixelFormatAttribfvARB(HDC hdc, GLint iPixelFormat, 
GLint iLayerPlane, GLuint nAttributes, 
const GLint *piAttributes, GLfloat *pfValues) ; 


These two variations of the same function allow you to query a particular pixelformat 
index and retrieve an array containing the attribute data for that pixelformat. The first 
argument, hdc, is the device context of the window that the pixelformat will be used for, 
followed by the pixelformat index. The iLayerPlane argument specifies which layer plane 
to query (0 if your implementation does not support layer planes). Next, nAttributes 
specifies how many attributes are being queried for this pixelformat, and the array 
piAttributes contains the list of attribute names to be queried. The attributes that can be 
specified are listed in Table 13.3. The final argument is an array that will be filled with the 
corresponding pixelformat attributes. 


TABLE 13.3  Pixelformat Attributes 


Constant Description 

WGL_NUMBER_PIXEL_FORMATS_ARB The number of pixelformats for this device. 

WGL_DRAW_TO_WINDOW_ARB Nonzero if the pixelformat can be used with a window. 

WGL_DRAW_TO_BITMAP_ARB Nonzero if the pixelformat can be used with a memory Device 
Independent Bitmap (DIB). 

WGL_DEPTH_BITS_ARB The number of bits in the depth buffer. 

WGL_STENCIL_BITS_ARB The number of bits in the stencil buffer. 

WGL_ACCELERATION_ARB One of the values in Table 13.4 that specifies which, if any, 


hardware driver is used. 
WGL_NEED_PALETTE_ARB Nonzero if a palette is required. 


Constant 


OpenGL and WGL Extensions 


Description 


WGL_NEED_SYSTEM_PALETTE_ARB 


WGL_SWAP_LAYER_BUFFERS_ARB 
WGL_SWAP_METHOD_ARB 


WGL_NUMBER_OVERLAYS_ARB 
WGL_NUMBER_UNDERLAYS_ARB 
WGL_TRANSPARENT_ARB 
WGL_TRANSPARENT_RED_VALUE_ARB 
WGL_TRANSPARENT_GREEN_VALUE_ARB 
WGL_TRANSPARENT_BLUE_VALUE_ARB 
WGL_TRANSPARENT_ALPHA_VALUE_ARB 
WGL_SHARE_DEPTH_ARB 


WGL_SHARE_STENCIL_ARB 


WGL_SHARE_ACCUM_ARB 


WGL_SUPPORT_GDI_ARB 
WGL_SUPPORT_OPENGL_ARB 
WGL_DOUBLE_BUFFER_ARB 
WGL_STEREO_ARB 
WGL_PIXEL_TYPE_ARB 


WGL_COLOR_BITS_ARB 
WGL_RED_BITS_ARB 
WGL_RED_SHIFT_ARB 
WGL_GREEN_BITS_ARB 
WGL_GREEN_SHIFT_ARB 
WGL_BLUE_BITS_ARB 
WGL_BLUE_SHIFT_ARB 
WGL_ALPHA_BITS_ARB 
WGL_ALPHA_SHIFT_ARB 
WGL_ACCUM_BITS_ARB 
WGL_ACCUM_RED_BITS_ARB 
WGL_ACCUM_GREEN_BITS_ARB 
WGL_ACCUM_BLUE_BITS_ARB 
WGL_ACCUM_ALPHA_BITS_ARB 
WGL_AUX_BUFFERS_ARB 


Nonzero if the hardware supports one palette only in 256-color 
mode. 

Nonzero if the hardware supports swapping layer planes. 
The method by which the buffer swap is accomplished for 
double-buffered pixelformats. It is one of the values listed in 
Table 13.5. 

The number of overlay planes. 

The number of underlay planes. 

Nonzero if transparency is supported. 

Transparent red color. 

Transparent green color. 

Transparent blue color. 

Transparent alpha color. 

Nonzero if layer planes share a depth buffer with the main 
plane. 

Nonzero if layer planes share a stencil buffer with the main 
plane. 

Nonzero if layer planes share an accumulation buffer with the 
main plane. 

Nonzero if GDI rendering is supported (front buffer only). 
Nonzero if OpenGL is supported. 

Nonzero if double buffered. 

Nonzero if left and right buffers are supported. 
WGL_TYPE_RGBA_ARB for RGBA color modes; 
WGL_TYPE_COLORINDEX_ARB for color index mode. 

Number of bit planes in the color buffer. 

Number of red bit planes in the color buffer. 

Shift count for red bit planes. 

Number of green bit planes in the color buffer. 

Shift count for green bit planes. 

Number of blue bit planes in the color buffer. 

Shift count for blue bit planes. 

Number of alpha bit planes in the color buffer. 

Shift count for alpha bit planes. 

Number of bit planes in the accumulation buffer. 

Number of red bit planes in the accumulation buffer. 
Number of green bit planes in the accumulation buffer. 
Number of blue bit planes in the accumulation buffer. 
Number of alpha bit planes in the accumulation buffer. 
The number of auxiliary buffers. 
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TABLE 13.4 Acceleration Flags for WGL_ACCELERATION_ARB 


Constant Description 
WGL_NO_ACCELERATION_ARB Software rendering, no acceleration 
WGL_GENERIC_ACCELERATION_ARB Acceleration via an MCD driver 
WGL_FULL_ACCELERATION_ARB Acceleration via an ICD driver 


TABLE 13.5 Buffer Swap Values for WGL_SWAP_METHOD_ARB 


Constant Description 

WGL_SWAP_EXCHANGE_ARB Swapping exchanges the front and back buffers. 
WGL_SWAP_COPY_ARB The back buffer is copied to the front buffer. 
WGL_SWAP_UNDEFINED_ARB The back buffer is copied to the front buffer, but the back buffer 


contents remain undefined after the buffer swap. 


If you want to call the wg1GetPixelFormatAttrib function, however, just like any other 
extension, the OpenGL rendering context must be current. This means that you must first 
create a temporary window, set up a pixelformat using PIXELFORMATDESCRIPTOR, and then 
retrieve and use a function pointer to one of the wg1lGetPixelFormatAttribARB functions. 
A convenient place to do this might be the splash screen or perhaps an initial Options 
dialog box that is presented to the user. You should not, however, try to use the Windows 
desktop because your application does not own it! 


The following simple example queries for a single attribute—the number of pixelformats 
supported—so that you know how many you may need to look at: 


int attrib[] = { WGL_NUMBER_PIXEL_FORMATS_ARB }; 

int nResults[Q]; 

wglGetPixelFormatAttributeivARB(hDC, 1, @, 1, attrib, nResults); 
// nResults[@] now contains the number of exported pixelformats 


For a more detailed example showing how to look for a specific pixelformat (including a 
multisampled pixelformat), see the SPHEREWORLD32 sample program coming up next. 


Win32 to the Max 

SPHEREWORLD32 is a Win32-specific version of the Sphere World example we have 
returned to again and again throughout this book. SPHEREWORLD32 allows you to select 
windowed or full-screen mode, changes the display settings if necessary, and detects and 
allows you to select a multisampled pixelformat. Finally, you use the Windows-specific 
font features to display the frame rate and other information onscreen. When in full- 
screen mode, you can even Alt+Tab away from the program, and the window will be mini- 
mized until reselected. 


OpenGL and WGL Extensions 


The complete source to this “ultimate” Win32 sample program, provided in Listing 3.10, 
contains extensive comments to explain every aspect of the program. In the initial dialog 
box that is displayed (see Figure 3.10), you can select full-screen or windowed mode, 
multisampled rendering (if available), and whether you want to enable the swap interval 
extension. A sample screen of the running program is shown in Figure 3.11. 


FIGURE 3.10 


f OpenGL Info —- 


| Vendor: ATI Technologies Inc. 
| Rendeter RADEON $700 PRO ¥86/SSE2 
| GL Version: 1.4.4103 WinXP Release 


| [160% 1200 32bpp @75hz | I VSync Buffer Swap 
| e 
| | FullScreen T™ MutiSempled Buffer 


| Window Ses ee in Options - 


=a) 


Concel | [OKI 


Initial Options dialog box for SPHEREWORLD32. 


Multisampled Frame Buffer 
FPS: 435.4 
OpenGL Rocks! 


FIGURE 3.11 


Output from the SPHEREWORLD32 sample program. 
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LISTING 13.10 SPHEREWORLD32 Source Code 


// SphereWor1d32.c 

// OpenGL SuperBible 

// Program by Richard S. Wright Jr. 

// This program demonstrates a full featured robust Win32 
// OpenGL framework 


TTTLTLT TTT TTT AAT 
// Include Files 


#include <windows.h> // Win32 Framework (No MFC) 
#include <gl\gl.h> // OpenGL 

#include <gl\glu.h> // GLU Library 

#include <stdio.h> // Standard I0 (sprintf) 
#include "..\..\common\wglext.h" // WGL Extension Header 
#include “..\..\common\glext.h" // OpenGL Extension Header 
#include "..\..\common\gltools.h" // GLTools library 
#include “resource.h" // Dialog resources 


// Initial rendering options specified by the user. 
struct STARTUPOPTIONS { 


DEVMODE devMode; // Display mode to use 

int nPixelFormat; // Pixel format to use 

int nPixelFormatMS; // Multisampled pixel format 
BOOL bFullScreen; // Full screen? 

BOOL bFSAA; 

BOOL bVerticalSync; 

}; 


TETTLT LTT TATA ALTA A TTT TT 
// Module globals 


static HPALETTE hPalette = NULL; // Palette Handle 

static HINSTANCE ghInstance = NULL; // Module Instance Handle 
static LPCTSTR lpszAppName = "SphereWorld32"; // Name of App 

static GLint nFontList; // Base display list for font 
static struct STARTUPOPTIONS startupOptions; // Startup options info 


static LARGE_INTEGER CounterFrequency; 
static LARGE_INTEGER FPSCount; 
static LARGE_INTEGER CameraTimer; 


OpenGL and WCGL Extensions 


LISTING 13.10 Continued 


#define NUM_SPHERES 30 // Number of Spheres 
GLTFrame spheres[NUM SPHERES]; // Location of spheres 
GLTFrame frameCamera; // Location and orientation of camera 


// Light and material Data 


GLfloat fLightPos[4] = { -100.0f, 100.0f, 50.0f, 1.0f }; // Point source 
GLfloat fNoLight[] = { 0.0f, @.0f, 0.0f, 0.Of }; 
GLfloat flowLight[] = { 0.25f, 0.25f, 0.25f, 1.0f }; 


GLfloat fBrightLight[] = { 1.0f, 1.0f, 1.0f, 1.0f }; 


// Shadow matrix 
GLTMatrix mShadowMatrix; 


// Textures identifiers 

#define GROUND TEXTURE 0 

#define TORUS_TEXTURE 1 

#define SPHERE_TEXTURE 2 

#define NUM_TEXTURES 3 

GLuint textureObjects[NUM_TEXTURES] ; 

const char *szTextureFiles[] = {"grass.tga", "“wood.tga", "“orb.tga"}; 


// Sphere and torus display lists 
GLuint l1TorusList, 1lSphereList; 


TUTLTTET TTT TAL TT AL TAL 
// Forward Declarations 


// Declaration for Window procedure 
LRESULT CALLBACK WndProc(HWND hWnd, UINT message, 
WPARAM wParam, LPARAM 1Param) ; 


// Startup Dialog Procedure 
BOOL APIENTRY StartupDlgProc (HWND hDlg, UINT message, 
UINT wParam, LONG lParam); 


// Find the best available pixelformat, including if Multisample is available 
void FindBestPF(HDC hDC, int *nRegularFormat, int *nMSFormat) ; 


BOOL ShowStartupOptions (void) ; // Initial startup dialog 
void ChangeSize(GLsizei w, GLsizei h); // Change projection and viewport 
void RenderScene(void) ; // Draw everything 
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LISTING 13.10 Continued 


void SetupRC(HDC hDC); // Set up the rendering context 
void ShutdownRC( void) ; // Shutdown the rendering context 
HPALETTE GetOpenGLPalette(HDC hDC); // Create a 3-3-2 palette 

void DrawInhabitants(GLint nShadow) ; // Draw inhabitants of the world 
void DrawGround(void) ; // Draw the ground 


PLLTLTTT LTT TTT TT TTL 
// Extension function pointers 

PFNWGLGETPIXELFORMATATTRIBIVARBPROC wglGetPixelFormatAttribivARB = NULL; 
PFNGLWINDOWPOS2IPROC glWindowPos2i = NULL; 

PFNWGLSWAPINTERVALEXTPROC wglSwapIntervalEXT = NULL; 


FTTTTTTT TTT TTA TATA TT TL 
// Window has changed size. Reset to match window coordinates 
void ChangeSize(GLsizei w, GLsizei h) 

{ 

GLfloat fAspect; 


// Prevent a divide by zero, when window is too short 
// (you can't make a window of zero width). 
if(h == 0) 


glViewport(®, @, w, h); 

fAspect = (GLfloat)w / (GLfloat)h; 

// Reset the coordinate system before modifying 
glMatrixMode(GL_PROJECTION) ; 


glLoadIdentity(); 


// Set the clipping volume 
gluPerspective(35.0f, fAspect, 1.0f, 50.0f); 


glMatrixMode(GL_MODELVIEW) ; 
glLoadidentity(); 
} 


FUTTTTTT LTT TTT TAT Tk 
// Draw the ground as a series of triangle strips 
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LISTING 13.10 Continued 


void DrawGround(void) 
{ 
GLfloat fExtent = 20.0f; 
GLfloat fStep = 1.0f; 
GLfloat y = -0.4f; 
GLfloat iStrip, iRun; 
GLfloat s = 0.0f; 
GLfloat t = 0.0f; 
GLfloat texStep = 1.0f / (fExtent * .075f); 


// Ground is a tiling texture 

glBindTexture(GL_TEXTURE_2D, textureObjects[GROUND_TEXTURE}) ; 
glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_REPEAT) ; 
glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_REPEAT); 


// Lay out strips and repeat textures coordinates 
for(iStrip = -fExtent; iStrip <= fExtent; iStrip += fStep) 
{ 
t = 0.0f; 
glBegin(GL_TRIANGLE_STRIP) ; 


for(iRun = fExtent; iRun >= -fExtent; iRun -= fStep) 
{ 
glTexCoord2f(s, t); 
glNormal3f(0.0f, 1.0f, 0.O0f); // All Point up 
glVertex3f(iStrip, y, iRun); 


glTexCoord2f(s + texStep, t); 
glNormal3f(@.0f, 1.0f, 0.0f); // All Point up 
glVertex3f(iStrip + fStep, y, iRun); 


t += texStep; 
} 
glEnd(); 
s += texStep; 
} 
} 


FETT TTT TATA A TAAL 
// Draw random inhabitants and the rotating torus/sphere duo 
void DrawInhabitants(GLint nShadow) 


{ 
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LISTING 13.10 Continued 


static GLfloat yRot = 0.0f; // Rotation angle for animation 
GLint i; 


if (nShadow == Q) 
{ 
yRot += 0.5f; 
glColor4f(1.0f, 1.0f, 1.0f, 1.0f); 
} 
else 
glColor4f(@.0f, @.0f, .@f, .75f); // Shadow color 


// Draw the randomly located spheres 
glBindTexture(GL_TEXTURE_2D, textureObjects[{SPHERE_TEXTURE] ); 
for(i = 0; i < NUM_SPHERES; i++) 

{ 

glPushMatrix(); 

gltApplyActorTransform(&spheres[i]) ; 

glCallList(1SphereList) ; 

glPopMatrix(); 

} 


glPushMatrix(); 
glTranslatef(0.0f, @.1f, -2.5f); 


glPushMatrix(); 
glRotatef(-yRot * 2.0f, 0.O0f, 1.0f, 0.0f); 
glTranslatef(1.0f, @.0f, 0.0f); 
glCallList(1SphereList) ; 

glPopMatrix(); 


if(nShadow == Q) 
{ 
// Torus alone will be specular 
glMaterialfv(GL_FRONT, GL_SPECULAR, fBrightLight) ; 


} 


glRotatef(yRot, @.0f, 1.0f, @.0f); 
glBindTexture(GL_TEXTURE_2D, textureObjects[TORUS_TEXTURE]) ; 
glCallList(1TorusList) ; 

glMaterialfv(GL_FRONT, GL_SPECULAR, fNoLight) ; 
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glPopMatrix(); 
} 


TETTTTTTT TTT TTT TTT 

// Draw everything 

void RenderScene(void) 
{ 
static int iFrames = 0; // Count frames to calculate fps every 100 frames 
static float fps = 0.0f; // Calculated fps 


// Clear the window 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT) ; 


glPushMatrix(); 
gltApplyCameraTransform(&frameCamera); // Move camera/world 


// Position light before any other transformations 
glLightfv(GL_LIGHT@, GL_POSITION, fLightPos) ; 


// Draw the ground 
glColorsf(1.0f, 1.0f, 1.0f); 
DrawGround(); 


// Draw shadows first 
glDisable(GL_DEPTH_TEST) ; 
glDisable(GL_LIGHTING) ; 
glDisable(GL_TEXTURE_2D) ; 
glEnable(GL_BLEND) ; 
glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) ; 
glEnable(GL_STENCIL_TEST) ; 
glPushMatrix() ; 

glMultMatrixf (mShadowMatrix) ; 

DrawInhabitants(1); 
glPopMatrix() ; 
glDisable(GL_STENCIL_TEST) ; 
glDisable(GL_BLEND) ; 
glEnable(GL_LIGHTING) ; 
glEnable(GL_TEXTURE_2D) ; 
glEnable(GL_DEPTH_TEST) ; 
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LISTING 13.10 Continued 


// Draw inhabitants normally 
DrawInhabitants(Q) ; 
glPopMatrix(); 


// Calculate Frame Rate, once every 100 frames 
iFrames++; 
if(iFrames == 100) 

{ 

float fTime; 


// Get the current count 
LARGE_INTEGER 1Current; 
QueryPerformanceCounter(&lCurrent) ; 


fTime = (float)(1Current.QuadPart - FPSCount.QuadPart) / 


(float )CounterFrequency.QuadPart; 
fps = (float)iFrames / fTime; 


// Reset frame count and timer 


iFrames = Q; 
QueryPerformanceCounter (&FPSCount) ; 
} 


// If we have the window position extension, display 
// the frame rate, and tell if multisampling was enabled 
// and if the VSync is turned on. 
if (glWindowPos2i != NULL) 
{ 
int iRow = 10; 
char cBuffer[64]; 


// Turn off depth test, lighting, and texture mapping 
glDisable(GL_DEPTH_TEST) ; 
glDisable(GL_LIGHTING) ; 
glDisable(GL_TEXTURE_2D) ; 
glColor3f(1.0f, 1.0f, 1.0f); 


// Set position and display message 
glWindowPos2i(0, iRow); 
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} 


glListBase(nFontList) ; 
glCallLists (13, GL_UNSIGNED BYTE, “OpenGL Rocks!"); 
iRow+= 20; 


// Display the frame rate 

sprintf (cBuffer,"FPS: %.1f", fps); 

glWindowPos2i(@, iRow); 

glCallLists(strlen(cBuffer), GL_UNSIGNED_BYTE, cBuffer) ; 
iRow += 20; 


// MultiSampled? 

if (startupOptions.bFSAA == TRUE && startupOptions.nPixelFormatMS != @) 
{ 
glWindowPos2i(@, iRow); 
glCallLists(25 ,GL_UNSIGNED BYTE,"Multisampled Frame Buffer") ; 
iRow += 20; 


} 


// VSync? 
if (wglSwapIntervalEXT != NULL && startupOptions.bVerticalSync == TRUE) 
{ 
glWindowPos2i(@, iRow); 
glCallLists(9 ,GL_UNSIGNED BYTE, "“VSync On"); 
iRow += 20; 
} 


// Put everything back 
glEnable(GL_DEPTH_TEST) ; 
glEnable(GL_LIGHTING) ; 
glEnable(GL_TEXTURE_2D) ; 
} 


LELETT TTT TTT TT A TTT TTL 
// Setup. Create font/bitmaps, load textures, create display lists 
void SetupRC(HDC hDC) 


{ 


GLTVector3 vPoints[3] = {{ 0.0f, -0.4f, 0.0f }, 


{ 10.0f, -0.4f, 0.0f }, 
{ 5.0f, -0.4f, -5.0f }}; 
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int iSphere; 
int i; 


// Setup the Font characteristics 
HFONT hFont; 
LOGFONT logfont; 


logfont.1fHeight = -20; 

logfont.1fWidth = Q; 

logfont.1fEscapement = Q; 
logfont.1fOrientation = 0; 

logfont.1fWeight = FW_BOLD; 

logfont.1fItalic = FALSE; 
logfont.1fUnderline = FALSE; 
logfont.1fStrikeOut = FALSE; 
logfont.1fCharSet = ANSI_CHARSET; 
logfont.1fOutPrecision = OUT_DEFAULT_PRECIS; 
logfont.1fClipPrecision = CLIP_DEFAULT_PRECIS; 
logfont.1fQuality = DEFAULT_QUALITY; 
logfont.1fPitchAndFamily = DEFAULT_PITCH; 
strcpy(logfont.1fFaceName, "Arial") ; 


// Create the font and display list 
hFont = CreateFontIndirect(&logfont) ; 
SelectObject (hDC, hFont); 


//Create display lists for glyphs ® through 128 
nFontList = glGenLists(128) ; 
wglUseFontBitmaps(hDC, 0, 128, nFontList); 


DeleteObject(hFont) ; // Don't need original font anymore 


// Grayish background 
glClearColor(fLowLight[®], flowLight[1], flowLight[2], flowLight[3]); 


// Clear stencil buffer with zero, increment by one whenever anybody 

// draws into it. When stencil function is enabled, only write where 

// stencil value is zero. This prevents the transparent shadow from drawing 
// over itself 

glStencil0p(GL_INCR, GL_INCR, GL_INCR); 
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glClearStencil(®); 
glStencilFunc(GL_EQUAL, x, @xQ1); 


// Cull backs of polygons 
glCullFace(GL_BACK) ; 
glFrontFace(GL_CCW) ; 
glEnable(GL_CULL_FACE) ; 
glEnable(GL_DEPTH_TEST) ; 


// Setup light parameters 
glLightModelfv(GL_LIGHT_MODEL_AMBIENT, fNoLight) ; 
glLightfv(GL_LIGHT@, GL_AMBIENT, fLowLight) ; 
glLightfv(GL_LIGHT®, GL_DIFFUSE, fBrightLight) ; 
glLightfv(GL_LIGHT®@, GL_SPECULAR, fBrightLight) ; 
glEnable(GL_LIGHTING) ; 

glEnable(GL_LIGHT®) ; 


// Calculate shadow matrix 
gltMakeShadowMatrix(vPoints, flightPos, mShadowMatrix) ; 


// Mostly use material tracking 
glEnable(GL_COLOR_MATERIAL) ; 
glColorMaterial(GL_FRONT, GL_AMBIENT_AND_ DIFFUSE) ; 
glMateriali(GL_FRONT, GL_SHININESS, 128); 


gltInitFrame(&frameCamera); // Initialize the camera 


// Randomly place the sphere inhabitants 
for(iSphere = @; iSphere < NUM_SPHERES; iSphere++) 
{ 
gltInitFrame(&spheres[iSphere]) ; // Initialize the frame 


// Pick a random location between -20 and 20 at .1 increments 
spheres[iSphere].vLocation[®] = (float)((rand() % 400) - 200) * 0.1f; 
spheres[iSphere].vLocation[1] = 0.0f; 

spheres[iSphere] .vLocation[2] (float)((rand() % 400) - 200) * 0.1f; 
} 


// Set up texture maps 
glEnable(GL_TEXTURE_2D) ; 
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LISTING 13.10 Continued 


glGenTextures(NUM_TEXTURES, textureObjects) ; 
glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE) ; 


// Load teach texture 
for(i = @; i < NUM_TEXTURES; i++) 
{ 
GLubyte *pBytes; 
GLint iWidth, iHeight, iComponents; 
GLenum eFormat; 


glBindTexture(GL_TEXTURE_2D, textureObjects[i]); 


// Load this texture map 
pBytes = gltLoadTGA(szTextureFiles[i], &iWidth, &iHeight, 
&iComponents, &eFormat) ; 
gluBuild2DMipmaps(GL_TEXTURE_2D, iComponents, iWidth, 
iHeight, eFormat, GL_UNSIGNED_BYTE, pBytes) ; 
free(pBytes) ; 


// Trilinear mipmapping 

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG FILTER, GL_LINEAR); 

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, 
GL_LINEAR_MIPMAP_LINEAR) ; 

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE); 

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO EDGE); 


} 


// Get window position function pointer if it exists 
glWindowPos2i = (PFNGLWINDOWPOS2IPROC)wglGetProcAddress("“glWindowPos2i") ; 


// Get swap interval function pointer if it exists 
wglSwapIntervalEXT = (PFNWGLSWAPINTERVALEXTPROC) 
wglGetProcAddress(“wglSwapIntervalEXT") ; 
if (wglSwapIntervalEXT != NULL && startupOptions.bVerticalSync == TRUE) 
wglSwapIntervalExT (1); 


// If multisampling was available and was selected, enable 
if (startupOptions.bFSAA == TRUE && startupOptions.nPixelFormatMS != 0) 
glEnable(GL_MULTISAMPLE_ARB) ; 
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LISTING 13.10 Continued 
// If separate specular color is available, make torus shiny 
if (gltIsExtSupported("GL_EXT_separate_specular_color")) 
glLightModeli(GL_LIGHT_MODEL_COLOR_CONTROL, GL_SEPARATE_SPECULAR_COLOR) ; 


// Initialize the timers 
QueryPerformanceFrequency (&CounterFrequency) ; 
QueryPerformanceCounter (&FPSCount) ; 
CameraTimer = FPSCount; 


a 


// Build display lists for the torus and spheres 
// (You could do one for the ground as well) 
lTorusList = glGenLists(2); 

1SphereList = 1TorusList + 1; 


glNewList(1lTorusList, GL_COMPILE) ; 
gltDrawTorus(®.35f, @.15f, 61, 37); 
glEndList(); 


glNewList(1SphereList, GL_COMPILE) ; 
gltDrawSphere(0.3f, 31, 16); 

glEndList(); 

} 


TETETTTT TTT A TA A AT TA 
// Shutdown the rendering context 
void ShutdownRC( void) 
{ 
glDeleteLists(nFontList, 128); // Delete font display list 
glDeleteLists(lTorusList, 2); // Delete object display lists 
glDeleteTextures(NUM_TEXTURES, textureObjects); // Release textures 
} 


FLTTTTT TTT TA TT A A 
// If necessary, creates a 3-3-2 palette for the device context listed. 
HPALETTE GetOpenGLPalette(HDC hDC) 

{ 

HPALETTE hRetPal = NULL; // Handle to palette to be created 

PIXELFORMATDESCRIPTOR pfd; // Pixel Format Descriptor 
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LOGPALETTE *pPal; // Pointer to memory for logical palette 
int nPixelFormat; // Pixel format index 

int nColors; // Number of entries in palette 

int i; // Counting variable 


BYTE RedRange, GreenRange, BlueRange; 
// Range for each color entry (7,7,and 3) 


// Get the pixel format index and retrieve the pixel format description 
nPixelFormat = GetPixelFormat(hDC) ; 
DescribePixelFormat(hDC, nPixelFormat, sizeof (PIXELFORMATDESCRIPTOR) , &pfd) ; 


// Does this pixel format require a palette? If not, do not create a 
// palette and just return NULL 
if(!(pfd.dwFlags & PFD_NEED_PALETTE) ) 

return NULL; 


// Number of entries in palette. 8 bits yields 256 entries 
nColors = 1 << pfd.cColorBits; 


// Allocate space for a logical palette structure plus all palette entries 
pPal = (LOGPALETTE*)malloc(sizeof (LOGPALETTE)+nColors*sizeof (PALETTEENTRY) ) ; 


// Fill in palette header 
pPal->palVersion = 0x300; // Windows 3.0 
pPal->palNumEntries = nColors; // table size 


// Build mask of all 1's. This creates a number represented by having 
// the low order x bits set, where x = pfd.cRedBits, pfd.cGreenBits, and 
// pfd.cBlueBits. 

RedRange = (1 << pfd.cRedBits) -1; 

GreenRange = (1 << pfd.cGreenBits) - 1; 

BlueRange = (1 << pfd.cBlueBits) -1; 


// Loop through all the palette entries 
for(i = 0; i < nColors; it+) 
{ 
// Fill in the 8-bit equivalents for each component 
pPal->palPalEntry[i].peRed = (i >> pfd.cRedShift) & RedRange; 
pPal->palPalEntry[i].peRed = (unsigned char) ( 
(double) pPal->palPalEntry[i].peRed * 255.0 / RedRange) ; 
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pPal->palPalEntry[i].peGreen = (i >> pfd.cGreenShift) & GreenRange; 
pPal->palPalEntry[i].peGreen = (unsigned char) ( 
(double) pPal->palPalEntry[i].peGreen * 255.0 / GreenRange) ; 


pPal->palPalEntry[i].peBlue = (i >> pfd.cBlueShift) & BlueRange; 
pPal->palPalEntry[i].peBlue = (unsigned char) ( 
(double) pPal->palPalEntry[i].peBlue * 255.0 / BlueRange) ; 


pPal->palPalEntry[i].peFlags = (unsigned char) NULL; 
} 


el 


// Create the palette 
hRetPal = CreatePalette(pPal) ; 


// Go ahead and select and realize the palette for this device context 
SelectPalette(hDC,hRetPal, FALSE) ; 
RealizePalette(hDC) ; 


// Free the memory used for the logical palette structure 
free(pPal) ; 


// Return the handle to the new palette 
return hRetPal; 
} 


FETTLTT TTT TTT TAT TT TTT ATL 
// Entry point of all Windows programs 
int APIENTRY WinMain( HINSTANCE hInstance, 

HINSTANCE hPrevInstance, 


LPSTR lpCmdLine, 

int nCmdShow) 
{ 
MSG msg; // Windows message structure 
WNDCLASS WC; // Windows class structure 
HWND hWnd; // Storage for window handle 


UINT uiStyle,uiStylex; 


712 CAHPTER 13 Wiggle: OpenGL on Windows 


LISTING 13.10 Continued 


ghInstance = hInstance; // Save instance handle 


// Get startup options, or shutdown 
if (ShowStartupOptions() == FALSE) 
return 0; 


if(startupOptions.bFullScreen == TRUE) 
if (ChangeDisplaySettings(&startupOptions.devMode, CDS_FULLSCREEN) 
!= DISP_CHANGE_SUCCESSFUL) 
{ 
// Replace with string resource, and actual width and height 
MessageBox(NULL, TEXT("Cannot change to selected desktop resolution."), 
NULL, MB_OK | MB_ICONSTOP); 


return -1; 
} 
// Register Window style 
we.style = CS_HREDRAW | CS_VREDRAW | CS_OWNDC; 
we. lpfnWndProc = (WNDPROC) WndProc; 
wc.cbClsExtra = 0; 
we.cbWndExtra = 0; 
we. hInstance = hInstance; 
we. hIcon = NULL; 
we. hCursor = LoadCursor(NULL, IDC_ARROW) ; 


// No need for background brush for OpenGL window 


we .hbrBackground = NULL; 
wc. 1pszMenuName = NULL; 
wc.1lpszClassName = lpszAppName; 


// Register the window class 
if (RegisterClass(&wc) == Q) 
return FALSE; 


// Select window styles 

if (startupOptions.bFullScreen == TRUE) 
{ 
uiStyle = WS_POPUP; 
uiStyleX = WS_EX_TOPMOST; 
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} 
else 
{ 
uiStyle = WS_OVERLAPPEDWINDOW; 
uiStylex = Q; 
} 


// Create the main 3D window 

hWnd = CreateWindowEx(uiStyleX, wc.lpszClassName, lpszAppName, uiStyle, 
@, ®, startupOptions.devMode.dmPelsWidth, 
startupOptions.devMode.dmPelsHeight, NULL, NULL, hInstance, NULL); 


// If window was not created, quit 
if (hWnd == NULL) 
return FALSE; 


// Make sure window manager stays hidden 
ShowWindow (hWnd , SW_SHOW) ; 
UpdateWindow( hWnd) ; 


// Process application messages until the application closes 
while( GetMessage(&msg, NULL, @, @)) 

{ 

TranslateMessage(&msg) ; 

DispatchMessage (&msg) ; 

} 


// Restore Display Settings 
if(startupOptions.bFullScreen == TRUE) 
ChangeDisplaySettings(NULL, 0); 


return msg.wParam; 


} 


FTTTTTT TTT TATA 

// Window procedure, handles all messages for this program 

LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) 
{ 
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LISTING 13.10 Continued 


static HGLRC hRC; // Permanent Rendering context 
static HDC hDC; // Private GDI Device context 


switch (message) 
{ 
// Window creation, setup for OpenGL 
case WM_CREATE: 
// Store the device context 
hDC = GetDC(hWnd) ; 


// The screen and desktop may have changed, so do this again 
FindBestPF(hDC, &startupOptions.nPixelFormat, 
&startupOptions.nPixelFormatMs) ; 


// Set pixelformat 
if(startupOptions.bFSAA == TRUE && 
(startupOptions.nPixelFormatMS != Q)) 
SetPixelFormat(hDC, startupOptions.nPixelFormatMS, NULL); 
else 
SetPixelFormat(hDC, startupOptions.nPixelFormat, NULL); 


// Create the rendering context and make it current 
hRC = wglCreateContext(hDC) ; 
wglMakeCurrent(hDC, hRC); 


// Create the palette 
hPalette = GetOpenGLPalette(hDC) ; 


SetupRC(hDC) ; 
break; 


// Check for ESC key 
case WM_CHAR: 
if (wParam == 27) 
DestroyWindow(hWnd) ; 
break; 


// Window is either full screen, or not visible 
case WM_ACTIVATE: 


{ 
// Ignore this altogether unless we are in full screen mode 
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if (startupOptions.bFullScreen == TRUE) 

{ 

// Construct windowplacement structure 

WINDOWPLACEMENT wndPlacement; 

wndPlacement.length = sizeof (WINDOWPLACEMENT) ; 

wndPlacement.flags = WPF_RESTORETOMAXIMIZED; 

wndPlacement.ptMaxPosition.x = 0; 

wndPlacement.ptMaxPosition.y = 

wndPlacement.ptMinPosition.x = 

wndPlacement.ptMinPosition.y = Q; 

wndPlacement.rcNormalPosition.bottom = 
startupOptions.devMode.dmPelsHeight; 

wndPlacement.rcNormalPosition.left = 0; 

wndPlacement.rcNormalPosition.top = Q; 

wndPlacement.rcNormalPosition.right = 
startupOptions.devMode.dmPelsWidth; 


! 1 ! 
Ss 8S 


// Switching away from window 

if (LOWORD(wParam) == WA_INACTIVE) 
{ 
wndPlacement.showCmd = SW_SHOWMINNOACTIVE; 
SetWindowPlacement(hWnd, &wndPlacement) ; 


ShowCursor (TRUE) ; 
} 

else // Switching back to window 
{ 


wndPlacement.showCmd = SW_RESTORE; 
SetWindowPlacement(hWnd, &wndPlacement) ; 
ShowCursor (FALSE) ; 

} 


} 
break; 


// Window is being destroyed, cleanup 
case WM_DESTROY: 
ShutdownRC() ; 


// Deselect the current rendering context and delete it 
wg1MakeCurrent(hDC, NULL) ; 
wglDeleteContext(hRC) ; 
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// Delete the palette 
if(hPalette != NULL) 
DeleteObject(hPalette) ; 


// Tell the application to terminate after the window 
// is gone. 
PostQuitMessage(Q); 

break; 


// Window is resized. 

case WM_SIZE: 
// Call our function which modifies the clipping 
// volume and viewport 
ChangeSize(LOWORD(1Param) , HIWORD(1Param) ); 

break; 


// The painting function. This message sent by Windows 
// whenever the screen needs updating. 
case WM_PAINT: 
{ 
// Only poll keyboard when this window has focus 
if (GetFocus() == hWnd) 
{ 
float fTime; 
float fLinear, fAngular; 


// Get the time since the last time we rendered a frame 
LARGE_INTEGER 1Current; 
QueryPerformanceCounter (&lCurrent) ; 


fTime = (float) (1Current.QuadPart - CameraTimer.QuadPart) / 
(float)CounterFrequency.QuadPart; 


CameraTimer = 1Current; 


// Camera motion will be time based. This keeps the motion constant 
// regardless of frame rate. Higher frame rates produce smoother 

// animation and motion, they should not produce "faster" motion. 
flinear = fTime * 1.0f; 

fAngular = (float)gltDegToRad(60.0f * fTime) ; 
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// Move the camera around, poll the keyboard 
if (GetAsyncKeyState(VK_UP) ) 
gltMoveFrameForward(&frameCamera, fLinear) ; 


if (GetAsyncKeyState (VK_DOWN) ) 
gltMoveFrameForward(&frameCamera, -fLinear); 


if (GetAsyncKeyState(VK_LEFT) ) 
gltRotateFrameLocalY(&frameCamera, fAngular) ; 
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if (GetAsyncKeyState(VK_RIGHT) ) 
gltRotateFrameLocalY(&frameCamera, -fAngular) ; 


// Call OpenGL drawing code 
RenderScene() ; 


// Call function to swap the buffers 
SwapBuffers(hDC) ; 


// Not validated on purpose, gives an endless series 
// of paint messages... this is akin to having 

// a rendering loop 

/ /ValidateRect (hWnd,NULL) ; 

} 


break; 


// Windows is telling the application that it may modify 
// the system palette. This message in essence asks the 
// application for a new palette. 
case WM_QUERYNEWPALETTE: 

// If the palette was created. 

if (hPalette) 


{ 
int nRet; 


// Selects the palette into the current device context 
SelectPalette(hDC, hPalette, FALSE); 


// Map entries from the currently selected palette to 
// the system palette. The return value is the number 
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// of palette entries modified. 
nRet = RealizePalette(hDC) ; 


// Repaint, forces remap of palette in current window 
InvalidateRect (hWnd, NULL, FALSE) ; 


return nRet; 


} 


break; 


// This window may set the palette, even though it is not the 
// currently active window. 
case WM_PALETTECHANGED: 
// Don't do anything if the palette does not exist, or if 
// this is the window that changed the palette. 
if((hPalette != NULL) && ((HWND)wParam != hWnd) ) 
{ 
// Select the palette into the device context 
SelectPalette(hDC,hPalette, FALSE) ; 


// Map entries to system palette 
RealizePalette(hDC) ; 


// Remap the current colors to the newly realized palette 
UpdateColors(hDC) ; 
return Q; 


} 
break; 


default: // Passes it on if unprocessed 
return (DefWindowProc(hWnd, message, wParam, lParam) ); 


return (QL); 


} 


FULTTTTTT TTT TTT TTT TT LT TTT Tk 
// Dialog procedure for the startup dialog 
BOOL APIENTRY StartupDlgProc (HWND hDlg, UINT message, UINT wParam, LONG lParam) 
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{ 
switch (message) 
{ 
// Initialize the dialog box 
case WM_INITDIALOG: 
{ 
int nPF; 
HDC hDC; // Dialogs device context 
HGLRC hRC; 
DEVMODE devMode; 
unsigned int iMode; 
unsigned int nWidth; // Current settings 
unsigned int nHeight; 
char cBuffer[64]; 
HWND hListBox; 
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PIXELFORMATDESCRIPTOR pfd = { // Not going to be too picky 
sizeof (PIXELFORMATDESCRIPTOR) , 
1, 
PFD_DRAW_TO_WINDOW | PFD_SUPPORT_OPENGL | PFD_DOUBLEBUFFER, 


PFD_TYPE_RGBA, // Full color 

32, // Color depth 
0,0,0,0,0,0,0, // Ignored 

0,0,0,0, // Accumulation buffer 
16, // Depth bits 

8, // Stencil bits 
0,0,0,0,0,0 }; // Some used, some not 


// Initialize render options 
startupOptions.bFSAA = FALSE; 
startupOptions.bFullScreen = FALSE; 
startupOptions.bVerticalSync = FALSE; 


// Create a "temporary" OpenGL rendering context 
hDC = GetDC(hD1g) ; 


// Set pixel format one time.... 

nPF = ChoosePixelFormat(hDC, &pfd); 

SetPixelFormat(hDC, nPF, &pfd); 

DescribePixelFormat(hDC, nPF, sizeof(PIXELFORMATDESCRIPTOR), &pfd); 
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// Create the GL context 
hRC = wglCreateContext(hDC) ; 
wglMakeCurrent(hDC, hRC); 


// Set text in dialog 
SetDlgItemText(hDlg, IDC_VENDOR, 

(const char *)glGetString(GL_VENDOR) ) ; 
SetDlgItemText(hDlg, IDC_RENDERER, 

(const char *)glGetString(GL_RENDERER) ) ; 
SetDlgItemText(hDlg, IDC_VERSION, 

(const char *)glGetString(GL_VERSION) ) ; 


// Vertical Sync off by default 
if (gltIsExtSupported("WGL_EXT_swap_control") ) 
EnableWindow(GetDlgItem(hDlg, IDC_VSYNC_CHECK), TRUE); 


// Find a multisampled and non-multisampled pixel format 
FindBestPF(hDC, &startupOptions.nPixelFormat, 
&startupOptions.nPixelFormatMS) ; 


// Done with GL context 
wglMakeCurrent(hDC, NULL); 
wglDeleteContext(hRC) ; 


// Enumerate display modes 
iMode = Q; 
nWidth = GetSystemMetrics(SM_CXSCREEN) ; // Current settings 
nHeight = GetSystemMetrics(SM_CYSCREEN) ; 
hListBox = GetDlgItem(hDlg, IDC_DISPLAY_COMBO) ; 
while(EnumDisplaySettings(NULL, iMode, &devMode) ) 
{ 
int iltem; 
sprintf (cBuffer,"%d x %d x %dbpp @%dhz", devMode.dmPelsWidth, 
devMode.dmPelsHeight, devMode.dmBitsPerPel, 
devMode.dmDisplayFrequency) ; 


iltem = SendMessage(hListBox, CB_ADDSTRING, @, (LPARAM)cBuffer) ; 
SendMessage(hListBox, CB_SETITEMDATA, iItem, iMode); 


if (devMode.dmPelsHeight == nHeight && 
devMode.dmPelsWidth == nWidth) 
SendMessage(hListBox, CB_SETCURSEL, ilItem, 0); 
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iModet++; 


} 


// Set other defaults ////////////1/ 
// Windowed or full screen 
CheckDlgButton(hDlg, IDC_FS CHECK, BST_CHECKED) ; 


// FSAA, but only if support detected 
if (startupOptions.nPixelFormatMS != Q) 
EnableWindow(GetDlgItem(hDlg, IDC_MULTISAMPLED CHECK), TRUE); 


return (TRUE); 
} 


break; 


// Process command messages 
case WM_COMMAND: 
{ 
// Validate and Make the changes 
if (LOWORD(wParam) == IDOK) 
{ 
// Read options //////////////1/11111111111111TITTTTTTTTT 
// Display mode 
HWND hListBox = GetDlgItem(hDlg, IDC_DISPLAY_COMBO) ; 
int iMode = SendMessage(hListBox, CB_GETCURSEL, 0, 0); 
iMode = SendMessage(hListBox, CB_GETITEMDATA, iMode, Q); 
EnumDisplaySettings(NULL, iMode, &startupOptions.devMode) ; 


// Full screen or windowed? 
if (IsDlgButtonChecked(hDlg, IDC_FS_CHECK) ) 
startupOptions.bFullScreen = TRUE; 
else 
startupOptions.bFullScreen = FALSE; 


/] FSAA 
if (IsDlgButtonChecked(hDlg, IDC_MULTISAMPLED_CHECK) ) 
startupOptions.bFSAA = TRUE; 
else 
startupOptions.bFSAA = FALSE; 
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LISTING 13.10 Continued 


// Vertical Sync. 

if (IsDlgButtonChecked(hDlg, IDC_VSYNC_CHECK) ) 
startupOptions.bVerticalSync = TRUE; 

else 
startupOptions.bVerticalSynce = FALSE; 


EndDialog(hD1g, TRUE) ; 
} 


if (LOWORD(wParam) == IDCANCEL) 
EndDialog(hDlg, FALSE); 


} 
break; 


// Closed from sysbox 
case WM_CLOSE: 
EndDialog(hDlg,FALSE); // Same as cancel 
break; 
} 


return FALSE; 
} 


FLTTTLTTT TTT TTT TATA ATT TTT 
// Display the startup screen (just a modal dialog box) 
BOOL ShowStartupOptions (void) 
{ 
return DialogBox (ghInstance, 
MAKEINTRESOURCE (IDD_DLG_INTRO) , 
NULL, 
StartupDlgProc) ; 


FTTLTTTTT TTT TTT TTT TTT ATT TTA TTT TTT TAL 
// Select pixelformat with desired attributes 

// Returns the best available "regular" pixel format, and the best available 

// Multisampled pixelformat (@ if not available) 

void FindBestPF(HDC hDC, int *nRegularFormat, int *nMSFormat) 


{ 
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*nRegularFormat = 0; 
*nMSFormat = 0; 


// easy check, just look for the entrypoint 
if (gltIsWGLExtSupported(hDC, "WGL_ARB_pixel_format")) 
if (wglGetPixelFormatAttribivARB == NULL) 
wglGetPixelFormatAttribivARB = (PFNWGLGETPIXELFORMATATTRIBIVARBPROC) 
wglGetProcAddress("“wglGetPixelFormatAttribivARB" ) ; 


El 


// First try to use new extended wgl way 
if (wglGetPixelFormatAttribivARB != NULL) 
{ 
// Only care about these attributes 
int nBestMS = Q; 
int a; 
int iResults[9]; 


int iAttributes [9] = { | WGL_SUPPORT_OPENGL_ARB, // 0 
WGL_ACCELERATION_ARB, // 1 
WGL_DRAW_TO_WINDOW_ARB, // 2 
WGL_DOUBLE_BUFFER_ARB, // 3 
WGL_PIXEL_TYPE_ARB, /1 4 
WGL_DEPTH_BITS_ARB, 115 
WGL_STENCIL_BITS_ARB, // 6 
WGL_SAMPLE_BUFFERS_ARB, // 7 
WGL_SAMPLES_ARB }; 11.8 


// How many pixelformats are there? 

int nFormatCount[] = { @ }; 

int attrib[] = { WGL_NUMBER_PIXEL_FORMATS_ ARB }; 
wglGetPixelFormatAttribivARB(hDC, 1, ®, 1, attrib, nFormatCount) ; 


// Loop through all the formats and look at each one 
for(i = 0; i < nFormatCount[@]; i++) 
{ 
// Query pixel format 
wglGetPixelFormatAttribivARB(hDC, i+1, @, 9, iAttributes, iResults) ; 


// Match? Must support OpenGL AND be Accelerated AND draw to Window 
if(iResults[®] == 1 && iResults[1] == WGL_FULL_ACCELERATION_ ARB 

&& iResults[2] == 1) 
if(iResults[3] == 1) // Double buffered 
if(iResults[4] == WGL_TYPE_RGBA_ARB) // Full Color 
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LISTING 13.10 Continued 


if(iResults[5] >= 16) // Any Depth greater than 16 
if(iResults[6] > 0) // Any Stencil depth (not zero) 
{ 
// We have a candidate, look for most samples if multisampled 
if (iResults[7] == 1) // Multisampled 
{ 
if(iResults[8] > nBestMS) // Look for most samples 
{ 
*nMSFormat = i; // Multisamples 
nBestMS = iResults[8]; // Looking for the best 
} 
} 
else // Not multisampled 
{ 


// Good enough for “regular”. This will fall through 
*nRegularFormat = i; 


} 


// Old fashioned way... 
// or multisample 


PIXELFORMATDESCRIPTOR pfd = { 
sizeof (PIXELFORMATDESCRIPTOR) , 


1, 


PFD_DRAW_TO_WINDOW 


PFD_TYPE_RGBA, 
32, 
0,0,0,0,0,0,0, 
0,0,0,0, 

24, 

8, 

@,0,0,0,0,0 }; 


PFD_SUPPORT_OPENGL | PFD_DOUBLEBUFFER, 


// 
// 
// 
// 
// 
// 
// 


Full color 

Color depth 

Ignored 
Accumulation buffer 
Depth bits 

Stencil bits 

Some used, some not 


*nRegularFormat = ChoosePixelFormat(hDC, &pfd); 


} 


Reference 


Summary 


This chapter introduced you to using OpenGL on the Win32 platform. You read about the 
different driver models and implementations available for Windows and what to watch. 
You also learned how to enumerate and select a pixel format to get the kind of hardware- 
accelerated or software rendering support you want. You’ve now seen the basic framework 
for a Win32 program that replaces the GLUT framework, so you can write true native 
Win32 application code. 


We also showed you how to create a 3-3-2 palette to enable OpenGL rendering with only 
256 available colors for output, and we showed you how to create a full-screen window for 
games or simulation-type applications. Additionally, we discussed some of the Windows- 
specific features of OpenGL on Windows, such as support for TrueType fonts and multiple 
rendering threads. 


Finally, we presented the ultimate OpenGL on Win32 sample program, SPHEREWORLD32. 
This program demonstrated how to use a number of Windows-specific features and WGL 
extensions if they were available. It also showed you how to construct a well-behaved 
program that will run on everything from an old 8-bit color display to the latest 32-bit 
full-color mega-3D game accelerator. 


Reference 


ChoosePixelFormat 

Purpose: Selects the pixel format closest to that specified by the PIXELFORMATDE - 
SCRIPTOR and that can be supported by the given device context. 

Include File: <wingdi.h> 

Syntax: 

int ChoosePixelFormat(HDC hDC, CONST PIXELFORMATDESCRIPTOR *ppfd); 


Description: This function enables you to determine the best available pixel format for 
a given device context based on the desired characteristics described in 
the PIXELFORMATDESCRIPTOR structure. This returned format index is then 
used in the SetPixelFormat function. 


Parameters: 


hDC HDC: The device context for which this function seeks a best-match pixel 
format. 
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pptd 


Returns: 


See Also: 


PIXELFORMATDESCRIPTOR*: A pointer to a structure that describes the ideal 
pixel format being sought. The entire contents of this structure are not 
pertinent to this function’s use. For a complete description of the 
PIXELFORMATDESCRIPTOR structure, see the DescribePixelFormat function. 
The relevant members for this function are as follows: 


nSize WORD: The size of the structure, usually set to 
sizeof (PIXELFORMATDESCRIPTOR). 
nVersion WORD: The version number of this structure, set to 1. 
dwFlag DworD: A set of flags that specify properties of the pixel 
buffer. 
iPixelType BYTE: The color mode (RGBA or color index) type. 
cColorBits BYTE: The depth of the color buffer. 
cAlphaBits BYTE: The depth of the alpha buffer. 
cAccumBits BYTE: The depth of the accumulation buffer. 


cDepthBits BYTE: The depth of the depth buffer. 
cStencilBits BYTE: The depth of the stencil buffer. 


cAuxBuf fers BYTE: The number of auxiliary buffers (not supported by 
Microsoft). 


iLayerType BYTE: The layer type (not supported by Microsoft). 


The index of the nearest matching pixel format for the logical format 
specified or zero if no suitable pixel format can be found. 


DescribePixelFormat, SetPixelFormat 


DescribePixelFormat 


Purpose: 
Include File: 
Syntax: 


Obtains detailed information about a pixel format. 


<wingdi.h> 


int DescribePixelFormat(HDC hDC, int iPixelFormat, UINT nBytes, 


Description: 


LPPIXELFORMATDESCRIPTOR ppfd) ; 


This function fills the PIXELFORMATDESCRIPTOR structure with information 
about the pixel format specified for the given device context. It also 
returns the maximum available pixel format for the device context. If 
ppfd is NULL, the function still returns the maximum valid pixel format 
for the device context. Some fields of the PIXELFORMATDESCRIPTOR are not 
supported by Microsoft’s generic implementation of OpenGL, but these 
values might be supported by individual hardware manufacturers. 


Parameters: 
hDCc 
iPixelFormat 


nBytes 


ppfd 
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HDC: The device context containing the pixel format of interest. 
int: The pixel format of interest for the specified device context. 


UINT: The size of the structure pointed to by ppfd. If this value is 0 (zero), 
no data will be copied to the buffer. It should be set to sizeof (PIXELFOR - 
MATDESCRIPTOR). 


LPPIXELFORMATDESCRIPTOR: A pointer to the PIXELFORMATDESCRIPTOR that, 
on return, will contain the detailed information about the pixel format of 
interest. The PIXELFORMATDESCRIPTOR structure is defined as follows: 


typedef struct tagPIXELFORMATDESCRIPTOR { 
WORD nSize; 
WORD nVersion; 
DWORD dwFlags; 
BYTE iPixelType; 
BYTE cColorBits; 
BYTE cRedBits; 
BYTE cRedShift; 
BYTE cGreenBits; 
BYTE cGreenShift; 
BYTE cBlueBits; 
BYTE cBlueShift; 
BYTE cAlphaBits; 
BYTE cAlphaShift; 
BYTE cAccumBits; 
BYTE cAccumReaBits; 
BYTE cAccumGreenBits; 
BYTE cAccumBlueBits; 
BYTE cAccumAlphaBits; 
BYTE cDepthBits; 
BYTE cStencilBits; 
BYTE cAuxBuffers; 
BYTE iLayerType; 
BYTE bReserved; 
DWORD dwLayerMask; 
DWORD dwVisibleMask; 
DWORD dwDamageMask ; 

} PIXELFORMATDESCRIPTOR; 


EL 


nSize contains the size of the structure. It should always be set to 
sizeof (PIXELFORMATDESCRIPTOR). 

nversion holds the version number of this structure. It should always be 
set to 1. 
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dwFlags contains a set of bit flags (see Table 13.1) that describe properties 
of the pixel format. Except as noted, these flags are not mutually exclu- 
sive. 

iPixelType specifies the type of pixel data. More specifically, it specifies 
the color selection mode. Valid values are GL_TYPE_RGBA for RGBA color 
mode or GL_TYPE_COLORINDEX for color index mode. 

cColorBits specifies the number of color bit planes used by the color 
buffer, excluding the alpha bit planes in RGBA color mode. In color 
index mode, it specifies the size of the color buffer. 


cRedBits specifies the number of red bit planes in each RGBA color 
buffer. 


cRedShift specifies the shift count for red bit planes in each RGBA color 
buffer. 


cGreenBits specifies the number of green bit planes in each RGBA color 
buffer. 


cGreenShift specifies the shift count for green bit planes in each RGBA 
color buffer. 


cBlueBits specifies the number of blue bit planes in each RGBA color 
buffer. 


cBlueShift specifies the shift count for blue bit planes in each RGBA 
color buffer. 


cAlphaBits specifies the number of alpha bit planes in each RGBA color 
buffer. This is not supported by the Microsoft generic implementation on 
Windows versions earlier than Windows 2000. 


cAlphaShift specifies the shift count for alpha bit planes in each RGBA 
color buffer. 


cAccumBits is the total number of bit planes in the accumulation buffer. 
See Chapter 7, “Imaging with OpenGL.” 


cAccumRedBits is the total number of red bit planes in the accumulation 
buffer. 


cAccumGreenBits is the total number of green bit planes in the accumula- 
tion buffer. 


cAccumBlueBits is the total number of blue bit planes in the accumula- 
tion buffer. 


cAccumAlphaBits is the total number of alpha bit planes in the accumula- 
tion buffer. 


cDepthBits specifies the depth of the depth buffer. 
cStencilBits specifies the depth of the stencil buffer. 


Reference 


cAuxBuffers specifies the number of auxiliary buffers. This is not 
supported by the Microsoft generic implementation. 

iLayerType is obsolete. Do not use. 

bReserved contains the number of overlay and underlay planes 

supported by the implementation. Bits 0 through 3 specify the number of 
overlay planes (up to 15), and bits 4 through 7 specify the number of 
underlay planes (also up to 15). 

dwLayerMask is obsolete. Do not use. 

dwVisibleMask is used in conjunction with the dwLayerMask to determine 


whether one layer overlays another. Layers are not supported by the 
current Microsoft implementation. 


dwDamageMask is obsolete. Do not use. 


Returns: The maximum pixel format supported by the specified device context or 
0 (zero) on failure. 

See Also: ChoosePixelFormat, GetPixelFormat, SetPixelFormat 

GetPixelFormat 

Purpose: Retrieves the index of the pixel format currently selected for the given 
device context. 

Include File: <wingdi.h> 

Syntax: 


int GetPixelFormat(HDC ADC) ; 


Description: This function retrieves the selected pixel format for the device context 
specified. The pixel format index is a one-based positive value. 


Parameters: 

hDc HDC: The device context of interest. 

Returns: The index of the currently selected pixel format for the given device or 0 
(zero) on failure. 

See Also: DescribePixelFormat, ChoosePixelFormat, SetPixelFormat 

SetPixelFormat 

Purpose: Sets a device context’s pixel format. 

Include File: <wingdi.h> 

Syntax: 


BOOL SetPixelFormat(HDC HDC, int nPixelFormat, 
CONST PIXELFORMATDESCRIPTOR * ppfd); 
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Description: This function actually sets the pixel format for a device context. After the 
pixel format has been selected for a given device, it cannot be changed. 
This function must be called before creating an OpenGL rendering 
context for the device. 


Parameters: 
hbc HDC: The device context whose pixel format is to be set. 
nPixelFormat int: Index of the pixel format to be set. 


pptfd LPPIXELFORMATDESCRIPTOR: A pointer to a PIXELFORMATDESCRIPTOR that 
contains the logical pixel format descriptor. This structure is used inter- 
nally to record the logical pixel format specification. Its value does not 
influence the operation of this function. 


Returns: TRUE if the specified pixel format was set for the given device context; 
FALSE if an error occurs. 

See Also: DescribePixelFormat, GetPixelFormat, ChoosePixelFormat 

SwapBuffers 

Purpose: Quickly copies the contents of a window’s back buffer to the front buffer 
(foreground), 

Include File: <wingdi.h> 

Syntax: 


BOOL SwapBuffers(HDC ADC); 


Description: When a double-buffered pixel format is chosen, a window has a front 
(displayed) and back (hidden) image buffer. Drawing commands are sent 
to the back buffer. This function enables you to copy the contents of the 
hidden back buffer to the displayed front buffer, to support smooth 
drawing or animation. Note that the buffers may be copied or just 
swapped by the implementation. After this command is executed, the 
contents of the back buffer are undefined. 


Parameters: 

hbc HDC: Specifies the device context of the window containing the offscreen 
and onscreen buffers. 

Returns: TRUE if the buffers were swapped. 


See Also: glDrawBuffer 


Reference 


wglCreateContext 

Purpose: Creates a rendering context suitable for drawing on the specified device 
context. 

Include File: <wingdi.h> 

Syntax: 


HGLRC wglCreateContext (HDC hDC) ; 


Description: This function creates an OpenGL rendering context suitable for the given 
windows device context. The pixel format for the device context should 
be set before the creation of the rendering context. When an application 
is finished with the rendering context, it should call wg1DeleteContext. 


Parameters: 

hDC HDC: The device context that will be drawn on by the new rendering 
context. 

Returns: The handle to the new rendering context or NULL if an error occurs. 

See Also: wglCreateLayerContext, wglDeleteContext, wglGetCurrentContext, 
wg1lMakeCurrent 


wglCreateLayerContext 


Purpose: Creates a new OpenGL rendering context suitable for drawing on the 
specified layer plane. 

Include File: <wingdi.h> 

Syntax: 


HGLRC wglCreateLayerContext(HDC ADC, int iLayerPlane) ; 


Description: This function creates an OpenGL rendering context suitable for the given 
layer plane. When overlay and underlay planes are supported (only by 
some hardware implementations), you need a separate OpenGL rendering 
context for each one. The layer plane with index 0 is the main plane 
(what you normally render to). Positive indexes are overlay planes, and 
negative values are underlay planes. 


Parameters: 


hDC HDC: The device context that will be drawn on by the new overlay or 
underlay rendering context. 


iLayerPlane int: The index of the layer plane for which to create the context. 
Returns: The handle to the new rendering context or NULL if an error occurs. 


See Also: wglCreateContext, wglDeleteContext, wglGetCurrentContext, 
wglMakeCurrent 
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wglCopyContext 

Purpose: Copies selected groups of rendering states from one OpenGL context to 
another. 

Include File: <wingdi.h> 

Syntax: 


BOOL wglCopyContext(HGLRC hSource, HGLRC hDest, UINT mask) ; 


Description: This function can be used to synchronize the rendering state of two 
OpenGL rendering contexts. Any valid state flags that can be specified 
with glPushAttrib can be copied with this function. You can use 
GL_ALL_ATTRIB_ BITS to copy all attributes. 


Parameters: 

hSource HGLRC: The source rendering context from which to copy state informa- 
tion. 

hDest HGLRC: The destination rendering context to which to copy state informa- 
tion. 

mask UINT: The handle of the rendering context to be deleted. 

Returns: TRUE if the rendering context state information is copied. 

See Also: glPushAttrib, wglCreateContext, wglGetCurrentContext, 
wglMakeCurrent 

wglDeleteContext 

Purpose: Deletes a rendering context after it is no longer needed by the applica- 
tion. 

Include File: <wingdi.h> 

Syntax: 


BOOL wglDeleteContext(HGLRC hglrc); 


Description: This function deletes an OpenGL rendering context. This frees any 
memory and resources held by the context. 


Parameters: 
hgire HGLRC: The handle of the rendering context to be deleted. 
Returns: TRUE if the rendering context is deleted; FALSE if an error occurs. It is an 


error for one thread to delete a rendering context that is the current 
context of another thread. 


See Also: wglCreateContext, wglGetCurrentContext, wglMakeCurrent 


Reference 


wg|DescribeLayerPlane 


Purpose: 


Include File: 
Syntax: 


Retrieves information about overlay and underlay planes of a given pixel 


format. 


<wingdi.h> 


BOOL wglDescribeLayerPlane(HDC hdc, int iPixelFormat, int iLayerPlane, 


Description: 


Parameters: 
hdc 


iPixelFormat 
iLayerPlane 


nBytes 
plpd 
Returns: 


UINT nBytes, LPLAYERPLANEDESCRIPTOR plpd); 


This function serves a purpose similar to DescribePixelFormat but 
retrieves information about overlay and underlay planes. Layered planes 
are numbered with negative and positive integers. Plane 0 is the main 
plane, and negative plane numbers are underlays. Numbers greater than 
0 are overlay planes. 


HDC: The handle of the device context whose layer planes are to be 
described. 


int: The pixel format of the desired layer plane. 


int: The overlay or underlay plane identifier. Negative values are under- 
lays, positive values are overlays, and 0 is the main plane. 


UINT: The size in bytes of the LAYERPLANEDESCRIPTOR. 
LPLAYERPLANEDESCRIPTOR: Pointer to a LAYERPLANEDESCRIPTOR structure. 


TRUE if successful and fills in the data members of the LAYER - 
PLANEDESCRIPTOR structure. This structure is defined as follows: 


typedef struct tagLAYERPLANEDESCRIPTOR { 
WORD nSize; 
WORD nVersion; 
DWORD dwFlags; 
BYTE iPixelType; 
BYTE cColorBits; 
BYTE cRedBits; 
BYTE cRedShift; 
BYTE cGreenBits; 
BYTE cGreenShift; 
BYTE cBlueBits; 
BYTE cBlueShift; 
BYTE cAlphaBits; 
BYTE cAlphaShift; 
BYTE cAccumBits; 
BYTE cAccumRedBits; 
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BYTE cAccumGreenBits; 

BYTE cAccumBlueBits; 

BYTE cAccumAlphaBits; 

BYTE cDepthBits; 

BYTE cStencilBits; 

BYTE cAuxBuffers; 

BYTE iLayerType; 

BYTE bReserved; 

COLOREF crTransparent; 
} LAYERPLANEDESCRIPTOR; 


nSize contains the size of the structure. It should always be set to 
sizeof (LAYERPLANEDESCRIPTOR). 


nVversion holds the version number of this structure. It should always be 
set to 1. 


dwFlags contains a set of bit flags that describe properties of the pixel 
format. Except as noted, these flags are not mutually exclusive: 
LPD_SUPPORT_OPENGL supports OpenGL rendering. 
LPD_SUPPORT_GDI supports GDI drawing. 
LPD_DOUBLEBUFFER indicates the layer plane is double-buffered. 
LPD_STEREO indicates the layer plane is stereoscopic. 


LPD_SWAP_EXCHANGE means that in double-buffering, the front 
and back buffers’ contents are swapped. 


LPD_SWAP_COPY means that in double-buffering, the back buffer is 
copied to the front buffer. The back buffer is unaffected. 


LPD_TRANSPARENT indicates the crTransparent member of this 
structure contains a color value that should be considered the 
transparent color. 
LPD_SHARE_DEPTH indicates the layer plane shares the depth 
buffer with the main plane. 
LPD_SHARE_STENCIL indicates the layer plane shares the stencil 
buffer with the main plane. 
LPD_SHARE_ACCUM indicates the layer plane shares the accumula- 
tion buffer with the main plane. 
iPixelType specifies the type of pixel data. More specifically, it specifies 
the color selection mode. Valid values are LPD_TYPE_RGBA for RGBA color 
mode or LPD_TYPE_COLORINDEX for color index mode. 
cColorBits specifies the number of color bit planes used by the color 


buffer, excluding the alpha bit planes in RGBA color mode. In color 
index mode, it specifies the size of the color buffer. 


See Also: 


Reference 


cRedBits specifies the number of red bit planes in each RGBA color 
buffer. 


cRedShift specifies the shift count for red bit planes in each RGBA color 
buffer. 


cGreenBits specifies the number of green bit planes in each RGBA color 
buffer. 


cGreenShift specifies the shift count for green bit planes in each RGBA 
color buffer. 


cBlueBits specifies the number of blue bit planes in each RGBA color 
buffer. 


cBlueShift specifies the shift count for blue bit planes in each RGBA 
color buffer. 


cAlphaBits specifies the number of alpha bit planes in each RGBA color 
buffer. This is not supported by the Microsoft generic implementation on 
Windows versions prior to Windows 2000. 


cAlphaShift specifies the shift count for alpha bit planes in each RGBA 
color buffer. This is not supported by the Microsoft implementation. 


cAccumBits is the total number of bit planes in the accumulation buffer. 


cAccumReadBits is the total number of red bit planes in the accumulation 
buffer. 


cAccumGreenBits is the total number of green bit planes in the accumula- 
tion buffer. 


cAccumBlueBits is the total number of blue bit planes in the accumula- 
tion buffer. 


cAccumAlphaBits is the total number of alpha bit planes in the accumula- 
tion buffer. 


cDepthBits specifies the depth of the depth buffer. 
cStencilBits specifies the depth of the stencil buffer. 


cAuxBuffers specifies the number of auxiliary buffers. This is not 
supported by the Microsoft generic implementation. 

iLayerType is the layer plane number. Positive values are overlays, and 
negative numbers are underlays. 

bReserved is not used. It must be 0 (zero). 

crTransparent indicates that when the LPD_TRANSPARENT flag is set, this 
is the transparent color value. Typically, it is set to black. The color is 
specified as a Windows COLORREF value. You can use the Windows RGB 
macro to construct this value. 


DescribePixelFormat, wglCreateLayerContext 
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wglGetCurrentContext 

Purpose: Retrieves a handle to the current thread’s OpenGL rendering context. 
Include File: <wingdi.h> 

Syntax: 


HGLRC wglGetCurrentContext (void) ; 


Description: Each thread of an application can have its own current OpenGL render- 
ing context. You can use this function to determine which rendering 
context is currently active for the calling thread. 


Returns: If the calling thread has a current rendering context, this function 
returns its handle. If not, the function returns NULL. 

See Also: wglCreateContext, wglDeleteContext, wglMakeCurrent, wglGetCurrentDC 

wg!GetCurrentDC 

Purpose: Gets the windows device context associated with the current OpenGL 
rendering context. 

Include File: <wingdi.h> 

Syntax: 


HDC wglGetCurrentDC (void) ; 


Description: This function enables you to acquire the windows device context of the 
window associated with the current OpenGL rendering context. It is typi- 
cally used to obtain a windows device context to combine OpenGL and 
GDI drawing functions in a single window. 


Returns: If the current thread has a current OpenGL rendering context, this func- 


tion returns the handle to the windows device context associated with it. 
Otherwise, the return value is NULL. 


See Also: wglGetCurrentContext 
wg!GetProcAddress 
Purpose: Gets the address of an extension function. 


Include File: <gl.h> 
Syntax: 
PROC wglGetProcAddress(LPSTR lpszProc) ; 


Description: This function retrieves the address of an extension function. If the exten- 
sion function is not available, a NULL pointer is returned. 


Reference 


Parameters: 

lpszProc LPSTR: The name of the extension function. 

Returns: None. 

wg!MakeCurrent 

Purpose: Makes a given OpenGL rendering context current for the calling thread 
and associates it with the specified device context. 

Include File: <wingdi.h> 

Syntax: 


BOOL wglMakeCurrent(HDC hDC, HGLRC HRC); 


Description: This function makes the specified rendering context the current render- 
ing context for the calling thread. This rendering context is associated 
with the given windows device context. The device context need not be 
the same as that used in the call to wglCreateContext, as long as the 
pixel format is the same for both and they both exist on the same physi- 
cal device (not one on the screen and one on a printer). Any outstanding 
OpenGL commands for the previous rendering context are flushed before 
the new rendering context is made current. You can also use this func- 
tion to make no rendering context active, by calling it with NULL for the 
ARC parameter. 


Parameters: 

hDC HDC: The device context that will be used for all OpenGL drawing opera- 
tions performed by the calling thread. 

ARC HGLRC: The rendering context to make current for the calling thread. 

Returns: TRUE on success or FALSE if an error occurs. If an error occurs, no render- 
ing context will remain current for the calling thread. 

See Also: wglCreateContext, wglDeleteContext, wglGetCurrentContext, 
wglGetCurrentDC 

wglShareLists 

Purpose: Allows multiple rendering contexts to share display lists. 

Include File: <wingdi.h> 

Syntax: 


BOOL wglShareLists(HGLRC hRC1, HGLRC hAC2); 
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Description: 
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A display list is a list of “precompiled” OpenGL commands and functions 
(see Chapter 11, “It’s All About the Pipeline: Faster Geometry 
Throughput”). Memory is allocated for the storage of display lists within 
each rendering context. As display lists are created within that rendering 
context, it has access to its own display list memory. This function allows 
multiple rendering contexts to share this memory. This capability is 
particularly useful when large display lists are used by multiple rendering 
contexts or threads to save memory. Any number of rendering contexts 
can share the same memory for display lists. This memory is not freed 
until the last rendering context using that space is deleted. When using a 
shared display list space between threads, you should synchronize display 
list creation and usage. 


Parameters: 

hRC1 HGLRC: The rendering context with which to share display list memory. 

hRC2 HGLRC: The rendering context that will share the display list memory with 
hRC1. No display lists for hRC2 should be created until after its display list 
memory is shared. 

Returns: TRUE if the display list space is shared; FALSE if they are not. 

See Also: glIsList, glNewList, glCallList, glCallLists, glListBase, 
glDeleteLists, glEndList, glGenLists 

wg|SwapLayerBuffers 

Purpose: Swaps the front and back buffers in the overlay, underlay, and main 
planes belonging to the specified device context. 

Include File: <wingdi.h> 

Syntax: 


BOOL wglSwapLayerBuffers(HDC hDC, UINT fuPlanes) ; 


Description: 


Parameters: 
hDC 


fuPlanes 


When a double-buffered pixel format is chosen, a window has a front 
(displayed) and back (hidden) image buffer. Drawing commands are sent 
to the back buffer. This function enables you to copy the contents of the 
hidden back buffer to the displayed front buffer, to support smooth 
drawing or animation. Note that the buffers are not really swapped. After 
this command is executed, the contents of the back buffer are undefined. 


HDC: The device context of the window containing the offscreen and 
onscreen buffers. 


UINT: The device context of the window containing the offscreen and 
onscreen buffers. 


Reference 


Returns: True if the buffers were swapped. 

See Also: glSwapBuf fers 

wglUseFontBitmaps 

Purpose: Creates a set of OpenGL display list bitmaps for the currently selected 
GDI font. 

Include File: <wingdi.h> 

Syntax: 


BOOL wglUseFontBitmaps(HDC hDC, DWORD dwFirst, DWORD dwCount, DWORD dwListBase) ; 


Description: This function takes the font currently selected in the device context spec- 
ified by hDC and creates a bitmap display list for each character, starting 
at dwFirst and running for dwCount characters. The display lists are 
created in the currently selected rendering context and are identified by 
numbers starting at dwListBase. Typically, this function enables you to 
draw text into an OpenGL double-buffered scene because the Windows 
GDI will not allow operations to the back buffer of a double-buffered 
window. This function also enables you to label OpenGL objects 
onscreen. 


Parameters: 


hDC HDC: The Windows GDI device context from which the font definition is 
to be derived. You can change the font used by creating and selecting the 
desired font into the device context. 


dwFirst DWORD: The ASCII value of the first character in the font to use for build- 
ing the display lists. 


dwCount DWORD: The consecutive number of characters in the font to use succeed- 
ing the character specified by dwFirst. 

dwListBase DWORD: The display list base value to use for the first display list character. 

Returns: TRUE if the display lists could be created; FALSE otherwise. 

See Also: wglUseFontOutlines, glIsList, glNewList, glCallList, glCallLists, 


glListBase, glDeleteLists, glEndList, glGenLists 


wglUseFontOutlines 
Purpose: Creates a set of OpenGL 3D display lists for the currently selected GDI 
font. 


Include File: <wingdi.h> 
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Syntax: 


BOOL wglUseFontOutlines(HDC hDC, DWORD first, DWORD count, DWORD listBase, 


Description: 


Parameters: 
hdc 

first 
count 
listBase 
deviation 
extrusion 
format 


lpgmf 


FLOAT deviation, FLOAT extrusion, int format, 
LPGLYPHMETRICSFLOAT Ipgmf) ; 


This function takes the TrueType font currently selected into the GDI 
device context hDC and creates a 3D outline for count characters starting 
at first. The display lists are numbered starting at the value listBase. 
The outline can be composed of line segments or polygons as specified 
by the format parameter. The character cell used for the font extends 1.0 
unit length along the x- and y-axes. The parameter extrusion supplies 
the length along the negative z-axis on which the character is extruded. 
The deviation is an amount 0 or greater that determines the chordal 
deviation from the original font outline. This function will work only 
with TrueType fonts. Additional character data is supplied in the lpgmf 
array Of GLYPHMETRICSFLOAT structures. 


HDC: Device context of the font. 

DworD: First character in the font to be turned into a display list. 

DWORD: Number of characters in the font to be turned into display lists. 
DWORD: The display list base value to use for the first display list character. 
FLOAT: The maximum chordal deviation from the true outlines. 

FLOAT: Extrusion value in the negative z direction. 


int: A value that specifies whether the characters should be composed of 
line segments or polygons in the display lists. It may be one of the 
following values: 


WGL_FONT_LINES: Use line segments to compose character. 
WGL_FONT_POLYGONS: Use polygons to compose character. 


LPGLYPHMETRICSFLOAT: Address of an array to receive glyphs metric data. 
Each array element is filled with data pertaining to its character’s display 
list. Each is defined as follows: 


typedef struct _GLYPHMETRICSFLOAT { // gmf 
FLOAT gmfBlackBoxx; 
FLOAT gmfBlackBoxyY; 
POINTFLOAT gmfptGlyphOrigin; 
FLOAT gmfCellIncx; 
FLOAT gmfCellincy; 
} GLYPHMETRICSFLOAT; 


Returns: 
See Also: 


Reference 


gmfBlackBoxx specifies the width of the smallest rectangle that 
completely encloses the character. 
gmfBlackBoxy specifies the height of the smallest rectangle that 
completely encloses the character. 
gmfptGlyphOrigin specifies the x and y coordinates of the upper-left 
corner of the rectangle that completely encloses the character. The 
POINTFLOAT structure is defined as 
typedef struct _POINTFLOAT { // ptf 

FLOAT x; // The horizontal coordinate of a point 


FLOAT Yy; // The vertical coordinate of a point 
} POINTFLOAT; 


gmfCellIncx specifies the horizontal distance from the origin of the 
current character cell to the origin of the next character cell. 


gmfCellIncy specifies the vertical distance from the origin of the current 
character cell to the origin of the next character cell. 


TRUE if the display lists could be created; FALSE otherwise. 


wglUseFontBitmaps, glIsList, glNewList, glCallList, glCallLists, 
glListBase, glDeleteLists, glEndList, glGenLists 
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CHAPTER 14 
OpenGL on MacOS X 


by Michael Sweet 
WHAT YOU'LL LEARN IN THIS CHAPTER: 
How To Functions You'll Use 
Choose appropriate pixel formats aglChoosePixelFormat 
for OpenGL rendering 
Manage OpenGL drawing contexts aglCreateContext, aglDestroyContext, 
aglSetCurrentContext, aglSetDrawable 
Do double-buffered drawing aglSwapBuffers 
Create bitmap text fonts aglUseFont 


This chapter discusses the OpenGL interfaces on MacOS X. We cover both AGL and 
NSOpenGL, the Carbon and Cocoa interfaces, respectively. You learn how to create and 
manage OpenGL contexts as well as how to create OpenGL drawing areas for Carbon and 
Cocoa applications. This chapter also shows you how to use GLUT on MacOS X with all 
the examples in this book. 


The Basics 


OpenGL on MacOS X is exposed via three APIs: AGL for Carbon applications, NsOpenGL 
for Cocoa applications, and CGL for applications that need direct access to the screen. 
This chapter discusses using AGL and NSOpenGL; the CGL API provides similar function- 
ality, but because it bypasses the windowing system (no OpenGL in windows, only full 
screen), we do not cover it. There is, however, a tutorial for CGL on the book’s Web site 
(see Appendix A, “Further Reading”). 


In addition to the three standard APIs, the Apple developer tools also include a GLUT port 
that can be used to compile and use any of the GLUT-based examples in this book. 
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Frameworks 


All the APIs discussed in this chapter are provided via frameworks in MacOS X. A frame- 
work is a collection of header files and libraries that provide specific functionality. Table 
14.1 lists the OpenGL-related frameworks discussed in this chapter. 


TABLE 14.1 OpenGL-Related Frameworks in MacOS X 


Name Description 

AGL Provides the OpenGL interface to Carbon (QuickDraw) windows. 

ApplicationServices Provides a common API for all GUI application services. This framework is 
used for all OpenGL applications. 

Carbon Provides a common API for MacOS X and earlier. This framework is used in 
combination with the AGL and OpenGL frameworks. 

Cocoa Provides the Aqua user interface classes. This framework is used in combina- 
tion with the OpenGL framework. 

OpenGL Provides the common OpenGL API to the graphics hardware. This framework 
is used with any of the other frameworks to provide OpenGL rendering 
support. 


Using the GLUT API 

The GLUT API is provided in the OpenGL examples folder of the Apple Developer Tools 
CD-ROM. To use the GLUT API, copy this folder to disk and then add the GLUT frame- 
work in the directory to the list of frameworks in the Xcode window for your application. 
Use the following linker options if you are building your software with a makefile: 


-framework /path/to/GLUT.framework -framework AGL -framework 
OpenGL -framework Carbon -framework ApplicationServices 


Using the AGL and Carbon APIs 


The AGL and Carbon APIs provide a relatively simple interface for C and C++ programs to 
display OpenGL graphics. Because Carbon-based applications are supported on MacOS 8 
through X, you can use the AGL and Carbon APIs to develop applications that work on 
multiple versions of MacOS. 


Programs of this type require the AGL, ApplicationServices, Carbon, and OpenGL frame- 
works; you can start with a Carbon-based application in the Xcode application and add 
the AGL and OpenGL frameworks or use the following linker options: 


-framework AGL -framework OpenGL -framework Carbon -framework ApplicationServices 


As you'll see in the following sections, AGL functions start with the prefix agl. 


Using the AGL and Carbon APIs 745 


Pixel Formats 

AGL exposes multiple pixel formats that provide different rendering capabilities. For 
example, a particular graphics card might be able to provide full-scene antialiasing with a 
16-bit depth buffer but not with a 24-bit or 32-bit depth buffer due to limited memory or 
other implementation-specific issues. 


The aglChoosePixelFormat function allows an application to choose an appropriate pixel 
format using a list of integer attributes describing the desired output capabilities. Table 
14.2 lists the attribute constants defined by the AGL API. 


TABLE 14.2. AGL Pixel Format Attribute List Constants 


Constant 


AGL_ACCELERATED 
AGL_ACCUM_ALPHA_SIZE 


AGL_ACCUM_BLUE_SIZE 


AGL_ACCUM_GREEN_SIZE 


AGL_ACCUM_RED_SIZE 


AGL_ALPHA_SIZE 


AGL_AUX_BUFFERS 


AGL_BACKING_ STORE 


AGL_BLUE_SIZE 


AGL_BUFFER_SIZE 


AGL_CLOSEST_POLICY 


AGL_DEPTH_SIZE 
AGL_DOUBLEBUFFER 
AGL_FULLSCREEN 
AGL_GREEN_SIZE 


AGL_LEVEL 


Description 


This constant specifies that a hardware-accelerated pixel format is required. 
The number that follows specifies the minimum number of alpha bits that 
are required in the accumulation buffer. 

The number that follows specifies the minimum number of blue bits that 
are required in the accumulation buffer. 

The number that follows specifies the minimum number of green bits that 
are required in the accumulation buffer. 

The number that follows specifies the minimum number of red bits that 
are required in the accumulation buffer. 

The number that follows specifies the minimum number of alpha bits that 
are required. 

The number that follows specifies the number of auxiliary buffers that are 
required. 

This constant specifies that only formats that support a full backing store 
capability should be used. 

The number that follows specifies the minimum number of blue bits that 
are required. 

The number that follows specifies the number of color index bits that are 
desired. 

This constant specifies that the sizes specified should be used as the ideal 
requirements for the pixel format, and the pixel format should use the 
closest number of bits possible. 

The number that follows specifies the minimum number of depth bits that 
are required. 

This constant specifies that a double-buffered visual is desired. 

This constant specifies that the pixel format is for full-screen rendering. 
The number that follows specifies the minimum number of green bits that 
are required. 

This constant specifies the buffer level in the number that follows; 0 is the 
main buffer, 1 is the first overlay buffer, —1 is the first underlay buffer, and 
so forth. 
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TABLE 14.2 Continued 
Constant Description 


AGL_MINIMUM_POLICY This constant specifies that the sizes specified should be used as the 
minimum requirements for the pixel format, and the pixel format should 
use the minimum number of bits possible. 

AGL_MAXIUM_POLICY This constant specifies that the sizes specified should be used as the 
minimum requirements for the pixel format, and the pixel format should 
use the maximum number of bits possible. 


AGL_NONE This constant specifies the end of the attribute list. 

AGL_OFFSCREEN This constant specifies that the pixel format is for an offscreen buffer. 

AGL_PIXEL_SIZE The number that follows specifies the total number of bits that are used for 
a pixel. 

AGL_RED_SIZE The number that follows specifies the minimum number of red bits that 
are required. 

AGL_RGBA This constant specifies that an RGBA visual is desired. 

AGL_STENCIL_SIZE The number that follows specifies the minimum number of stencil bits that 
are required. 

AGL_STEREO This constant specifies that a stereo visual is desired; stereo visuals provide 


separate left and right eye images. 


You might use the following code to find a double-buffered RGB pixel format: 


GLint attributes[] = { 
AGL_RGBA, 
AGL_DOUBLEBUFFER, 
AGL_RED_SIZE, 4, 
AGL_GREEN_SIZE, 4, 
AGL_BLUE_SIZE, 4, 
AGL_DEPTH_SIZE, 16, 
AGL_NONE 

}5 

AGLPixelFormat format; 


format = aglChoosePixelFormat(NULL, ®, attributes) ; 


Note that the last value is required to be AGL_NONE. After ag1ChoosePixelFormat is called, 
an AGLPixelFormat value is returned; this value provides information on the correct pixel 
format to use. If no matching pixel format can be found, a NULL pointer is returned, and 

you should retry with different attributes or inform the users that the window cannot be 
displayed on their system. 
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Managing Contexts 


AGL provides four functions for managing OpenGL rendering contexts: 
aglCreateContext, aglDestroyContext, aglSetCurrentContext, and aglSetDrawable. The 
aglCreateContext function creates an OpenGL context using the AGLPixelFormat value 
returned by the ag1ChoosePixelFormat function: 


AGLContext context; 
context = aglCreateContext(format, NULL); 


The aglCreateContext function accepts two arguments: the pixel format and a context to 
share display list, texture object, and vertex array information with. Pass NULL if you do 
not want to share information with another context. 


After you have created the context, it needs to be bound to a window or offscreen buffer 
using the ag1SetDrawable function: 


WindowPtr window; 
aglSetDrawable(context, GetWindowPort (window) ) ; 


Next, call the aglSetCurrentContext function to use the context to do OpenGL rendering: 


aglSetCurrentContext (context) ; 


Finally, when you are done using the context, call the ag1DestroyContext function to 
release the resources that were used by the context: 


aglDestroyContext (context) ; 


Doing Double-Buffered Rendering 

You enable double-buffered rendering by using the appropriate pixel format. The drawing 
code in your program then merely needs to call the ag1SwapBuffers function after doing 
any OpenGL rendering to make it visible: 


aglSwapBuffers(context) ; 


Your First AGL Program 

Listing 14.1 shows a basic Carbon application that creates a window for OpenGL render- 
ing and displays a spinning cube. The application responds to mouse clicks and drags to 
alter the spinning of the cube and exits after the user closes the window. Figure 14.1 
shows the result. 
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(Rees) Carbon OpenGL Example 


FIGURE 14.1 The AGL spinning cube example. 


LISTING 14.1 The CARBON Sample Program 
/* 

* Include necessary headers... 

= 


#include <stdio.h> 
#include <stdlib.h> 
#include <Carbon/Carbon.h> 
#include <AGL/agl.h> 


/* 
* Globals... 
sa J 
float CubeRotation[3], /* Rotation of cube */ 
CubeRate[3]; /* Rotation rate of cube */ 
int CubeMouseButton, /* Button that was pressed */ 
CubeMousex, /* Start X position of mouse */ 
CubeMouseY; /* Start Y position of mouse */ 


int Cubex, /* X position of window */ 
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CubeY, /* Y position of window */ 
CubeWidth, /* Width of window */ 
CubeHeight; /* Height of window */ 
int CubeVisible; /* Is the window visible? */ 
AGLContext CubeContext; /* OpenGL context */ 
/* 
* Functions... 
sai 
void DisplayFunc(void) ; 


static pascal OSStatus 
EventHandler(EventHandlerCallRef nextHandler, 
EventRef event, void *userData) ; 


void IdleFunc(void) ; 

void MotionFunc(int x, int y); 

void MouseFunc(int button, int state, int x, int y); 

void ReshapeFunc(int width, int height); 

/* 

* 'main()' - Main entry for example program. 

sf 

int /* 0 - Exit status: */ 

Main(int argc, /* I - Number of command-line args */ 

char *argv[]) /* I - Command-line args */ 

{ 
AGLPixelFormat format; /* OpenGL pixel format */ 
WindowPtr window; /* Window */ 
int winattrs; /* Window attributes */ 
str255 title; /* Title of window */ 
Rect rect; /* Rectangle definition */ 
EventHandlerUPP handler; /* Event handler */ 
EventLoopTimerUPP thandler; /* Timer handler */ 
EventLoopTimerRef timer; /* Timer for animating the window */ 
ProcessSerialNumber = psn; /* Process serial number */ 
static EventTypeSpec events[] = /* Events we are interested in... */ 

{ 


{ kEventClassMouse, kEventMouseDown }, 
{ kEventClassMouse, kEventMouseUp }, 
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LISTING 14.1 Continued 


kEventClassMouse, kEventMouseMoved }, 
kEventClassMouse, kEventMouseDragged }, 
kEventClassWindow, kEventWindowDrawContent }, 
kEventClassWindow, kEventWindowShown }, 
kEventClassWindow, kEventWindowHidden }, 
kEventClassWindow, kEventWindowActivated }, 
kEventClassWindow, kEventWindowDeactivated }, 
kEventClassWindow, kEventWindowClose }, 
kEventClassWindow, kEventWindowBoundsChanged } 


SERA A HAS 


}; 
static GLint attributes[] = /* OpenGL attributes */ 
{ 
AGL_RGBA, 
AGL_GREEN_SIZE, 1, 
AGL_DOUBLEBUFFER , 
AGL_DEPTH_SIZE, 16, 


AGL_NONE 
}; 
//Set initial values for window 
const int orig“WinHeight = 628; 
const int origWinWidth = 850; 
const int origWinxOffset = 50; 
const int origWinYOffset = 50; 
/* 
* Create the window... 
*/ 
CubeContext = Q; 
CubeVisible = 0; 


SetRect(&rect, origWinxOffset, origWinYOffset, origWinWidth, origWinHeight) ; 


winattrs = kWindowStandardHandlerAttribute | kWindowCloseBoxAttribute | 
kWindowCollapseBoxAttribute | kWindowFullZoomAttribute | 
kWindowResizableAttribute | kWindowLiveResizeAttribute; 

winattrs &= GetAvailableWindowAttributes (kDocumentWindowClass) ; 


strepy(title + 1, "Carbon OpenGL Example"); 
title[@] = strlen(title + 1); 
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CreateNewindow(kDocumentWindowClass, winattrs, &rect, &window); 
SetWTitle(window, title); 


handler = NewEventHandlerUPP(EventHandler) ; 
InstallWindowEventHandler(window, handler, 

sizeof(events) / sizeof(events[Q@]), 

events, NULL, QL); 
thandler = 

NewEventLoopTimerUPP( (void (*)(EventLoopTimerRef, void *))IdleFunc); 
InstallEventLoopTimer(GetMainEventLoop(), ®, @, thandler, 
@, &timer) ; 


GetCurrentProcess (&psn) ; 
SetFrontProcess(&psn) ; 


DrawGrowIcon(window) ; 
ShowWindow(window) ; 
/* 


* Create the OpenGL context and bind it to the window... 
a 


format 
CubeContext 


aglChoosePixelFormat(NULL, ®, attributes) ; 
aglCreateContext(format, NULL) ; 


if (!CubeContext) 


{ 
puts("Unable to get OpenGL context!"); 
return (1); 


} 


aglDestroyPixelFormat (format) ; 
aglSetDrawable(CubeContext, GetWindowPort (window) ) ; 


/* 

* Setup remaining globals... 
mi 

CubeX = 50; 

CubeY = 50; 
CubeWidth = 400; 
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LISTING 14.1 Continued 


CubeHeight = 400; 
CubeRotation[@] = 45.0f; 
CubeRotation[1] = 45.0f; 
CubeRotation[2] = 45.0f; 
CubeRate[0] = 1.0Ff; 
CubeRate[1] = 1.0Ff; 


CubeRate[2] 1.0f; 


//Set the initial size of the cube 

ReshapeFunc(orig“WinWidth - origWinXOffset, origWinHeight - origWinYOffset) ; 
{* 
* Loop forever... 
wy 


for (55) 
{ 
if (CubeVisible) 
SetEventLoopTimerNextFireTime(timer, 0.05); 


RunApplicationEventLoop() ; 


if (CubeVisible) 

{ 
/* 
* Animate the cube... 
¥/ 


DisplayFunc(); 
} 


/* 
* 'DisplayFunc()' - Draw a cube. 
i! 


void 
DisplayFunc (void) 
{ 


int = Os he /* Looping vars */ 
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Continued 
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float 


aspectRatio,windowidth, windowHeight; 


static const GLfloat corners[8][3] = /* Corner vertices */ 


static const int 


static const GLfloat 


/* 


{ 
{ 1208, S120%) 108 =}; 
{ AQF, =10f,. 1.0F 3; 
{ <4), Of -=4.6Ts TL Gteh, 
{<1 2085, 1.085 > Lt: 
{> WeOhs 2 - 1.08, -AROt ys 
{ 1.0f, -1.0f, -1.0f }, 
{ -1.0f, -1.0f, -1.0f }, 
{ -AZ0f SOF}: 1 0F} 
hs 
sides[6][4] = /* Sides */ 
{ 
{ 0, 1, 2, 3}, 
{ 4, 5, 6, 7 }, 
{OSs 1;, Ss. A}; 
{a2 idige the alah 
1341s Sigs tig, cae hs 
£1 eee (Oe ory 
}5 
colors[6][3] = /* Colors */ 
{ 
{ 1.0f, 0.Of, 0.O0f }, 
{ 0.0f, 1.0f, 0.Of }, 
{ 1.0f, 1.0f, 0.Of }, 
{-0,0F; 6.0, 1.08 -}— 
{ 1.0f, 0.0f, 1.0f }, 
{ 0.0f, 1.0f, 1.0fF } 
}5 


* Set the current OpenGL context.. 


= 


aglSetCurrentContext (CubeContext) ; 


/* 


* Clear the window... 


<i 


/* Front top right */ 
/* Front bottom right */ 


/* 
[* 
Lx 
/* 
/* 
/* 


/* 
/* 
/* 
/* 
/* 
/* 


[* 
[* 
/* 
/* 
/* 
/* 


Front bottom left */ 
Front top left */ 
Back top right */ 
Back bottom right */ 
Back bottom left */ 
Back top left */ 


Front */ 
Back */ 
Right */ 
Left */ 
Top */ 
Bottom */ 


Red */ 
Green */ 
Yellow */ 
Blue */ 
Magenta */ 
Cyan */ 
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LISTING 14.1 Continued - 


glViewport(@, @, CubeWidth, CubeHeight) ; 
glClearColor(0.0f, 0.0f, 0.0f, 0.0f); 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


/* 
* Setup the matrices... 
a 


glMatrixMode(GL_PROJECTION) ; 

glLoadidentity(); 
aspectRatio = (GLfloat)CubeWidth / (GLfloat)CubeHeight; 
if (CubeWidth <= CubeHeight) 


{ 

windowidth = 2.0f; 

windowHeight = 2.0f / aspectRatio; 

glOrtho(-2.0f, 2.0f, -windowHeight, windowHeight, 2.0f, -2.0f); 
} 
else 
{ 

windowidth = 2.0f * aspectRatio; 

windowHeight = 2.0f; 

glOrtho(-windowHeight, windowHeight, -2.0f, 2.0f, 2.0f, -2.0f); 
} 


glMatrixMode (GL_MODELVIEW) ; 

glLoadiIdentity(); 

glRotatef(CubeRotation[®], 1.0f, 0.0f, 0.0f); 
glRotatef(CubeRotation[1], 0.0f, 1.0f, 0.0f); 
glRotatef(CubeRotation[2], 0.0f, 0.Of, 1.0f); 


[* 

* Draw the cube... 

%/ 
glEnable(GL_DEPTH_TEST) ; 
g1lBegin(GL_QUADS) ; 

for (i = 0; i < 6; i ++) 


{ 
glColor3fv(colors[i]); 
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LISTING 14.1 Continued 
for (j = @; j < 4; j ++) 
glVertex3fv(corners[sides[i][j]]); 


glEnd(); 


/* 
* Swap the front and back buffers... 
a | 


aglSwapBuffers(CubeContext) ; 
} 


/* 
* 'EventHandler()' - Handle window and mouse events from the window manager. 
= 


static pascal OSStatus // 0 - noErr on success or error code 
EventHandler(EventHandlerCallRef nextHandler, /* I - Next handler to call */ 
EventRef event, /* I - Event reference */ 
void *userData) /* I - User data (not used) */ 
{ 
UInt32 kind; /* Kind of event */ 
Rect rect; /* New window size */ 
EventMouseButton button; /* Mouse button */ 
Point point; /* Mouse position */ 


kind = GetEventKind(event) ; 


if (GetEventClass(event) == kEventClassWindow) 
{ 
switch (kind) 
{ 
case kEventWindowDrawContent : 
if (CubeVisible && CubeContext) 
DisplayFunc(); 
break; 


case kEventWindowBoundsChanged : 
GetEventParameter(event, kEventParamCurrentBounds, typeQDRectangle, 
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LISTING 14.1 Continued 


NULL, sizeof(Rect), NULL, &rect); 


Cubex 
CubeY 


rect. left; 
rect.top; 


if (CubeContext) 
aglUpdateContext (CubeContext) ; 


ReshapeFunc(rect.right - rect.left, rect.bottom - rect.top); 


if (CubeVisible && CubeContext) 
DisplayFunc(); 
break; 


case kEventWindowShown : 
CubeVisible = 1; 
if (CubeContext) 
DisplayFunc(); 
break; 


case kEventWindowHidden : 
CubeVisible = 0; 


break; 


case kEventWindowClose : 


ExitToShell(); 
break; 
} 
i 
else 
{ 
switch (kind) 
{ 


case kEventMouseDown : 
GetEventParameter(event, kEventParamMouseButton, typeMouseButton, 
NULL, sizeof (EventMouseButton), NULL, &button); 
GetEventParameter(event, kEventParamMouseLocation, typeQDPoint, 
NULL, sizeof(Point), NULL, &point); 


if (point.v < CubeY |} 
(point.v > (CubeY + CubeHeight - 8) && 
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LISTING 14.1 Continued 


point.h > (CubeX + CubeWidth - 8))) 
return (CallNextEventHandler(nextHandler, event) ); 


MouseFunc(button, ®, point.h, point.v); 
break; 


case kEventMouseUp : 
GetEventParameter(event, kEventParamMouseButton, typeMouseButton, 
NULL, sizeof (EventMouseButton), NULL, &button); 
GetEventParameter(event, kEventParamMouseLocation, typeQDPoint, 
NULL, sizeof(Point), NULL, &point); 


if (point.v < CubeY |} 
(point.v > (CubeY + CubeHeight - 8) && 
point.h > (CubeX + CubeWidth - 8))) 
return (CallNextEventHandler(nextHandler, event)); 


MouseFunc(button, 1, point.h, point.v); 
break; 


case kEventMouseDragged : 
GetEventParameter(event, kEventParamMouseLocation, typeQDPoint, 
NULL, sizeof(Point), NULL, &point); 


if (point.v < CubeY {|} 
(point.v > (CubeY + CubeHeight - 8) && 
point.h > (CubeX + CubeWidth - 8))) 
return (CallNextEventHandler(nextHandler, event) ); 


MotionFunc(point.h, point.v); 


break; 
default : 
return (CallNextEventHandler(nextHandler, event)); 
} 
} 
/* 


* Return whether we handled the event... 
i 
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LISTING 14.1 Continued 


return (noErr) ; 


/* 
* 'TdleFunc()' - Rotate and redraw the cube. 
*/ 


void 

IdleFunc(void) 

{ 
CubeRotation[0] += CubeRate[Q]; 
CubeRotation[1] += CubeRate[1]; 
CubeRotation[2] += CubeRate[2]; 


QuitApplicationEventLoop() ; 


/* 
* 'MotionFunc()' - Handle mouse pointer motion. 
aff 


void 
MotionFunc(int x, /* I - X position */ 
int y) /* I - Y position */ 
{ 
/* 
* Get the mouse movement... 
*) 


CubeMousex; 
CubeMouseY; 


/* 

* Update the cube rotation rate based upon the mouse movement and 
* button... 

=) 


switch (CubeMouseButton) 
{ 


case Q: /* Button 1 */ 
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Using the AGL and Carbon APIs 


CubeRate[0] = 
CubeRate[1] = 
CubeRate[2] = 


break; 


case 1: 


CubeRate[0] = 
CubeRate[1] = 
CubeRate[2] = 


break; 


default : 


CubeRate[Q] = 
CubeRate[1] = 
CubeRate[2] = 


break; 


/* 


Ss 


.O1F 
.O1F 
OF; 


OF; 
.O1f 
.O1F 


.O1F 
.OF; 
.O1F 


Yy; 


y3 


Ys 


x; 


/* 


/* 


Button 2 */ 


Button 3 */ 


* 'MouseFunc()' - Handle mouse button press/release events. 


os 


void 
MouseFunc(int button, 
int state, 
int x, 
int y) 
{ 
/* 


* Only respond to button presses... 


i | 


if (state) 
return; 


/* 


* Save the mouse state... 


| 


{* 
/* 
/* 
{* 


I - Button that was pressed */ 
I - Button state (®@ = down) */ 
I - X position */ 
I - Y position */ 
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LISTING 14.1 Continued 


CubeMouseButton = button; 
CubeMouseX = X; 
CubeMouseY =y; 
/* 
* Zero-out the rotation rates... 
| 
CubeRate[0] = 0.0f; 
CubeRate[1] = 0.0f; 
CubeRate[2] = 0.0f; 
} 
/* 
* 'ReshapeFunc()' - Resize the window. 
st | 
void 
ReshapeFunc(int width, /* I - Width of window */ 
int height) /* I - Height of window */ 
{ 
CubeWidth = width; 
CubeHeight = height; 
} 


Using Bitmap Fonts 

The AGL framework provides a single function for using bitmap fonts for OpenGL render- 
ing: aglUseFont. This function works in conjunction with the Carbon GetFNum function 
and OpenGL glGenLists function to extract bitmaps and create display lists for each char- 
acter you want in the font. The following code demonstrates how to extract the visible 
ASCII characters from the Courier New Bold font at a 14-pixel-high size: 


GLint listbase; 
short font; 
Str255 fontname; 


strepy(fontname + 1, "Courier New"); 
fontname[®] = strlen(fontname + 1); 


GetFNum(fontname, &font) ; 
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listbase = glGenLists(96) ; 
aglUseFont(context, font, bold, 14, ', 96, listbase) ; 


The font number is used along with a font style (bold in this case) to select the actual font 
to render. The fifth and sixth arguments are the starting character and the number of 
characters to extract, respectively. The listbase variable in the example points to the start 
of a block of 96 consecutive display lists to use for each character. 


After the characters are extracted, you can draw text using a combination of the 
glRasterPos(), glPushAttrib(), glListBase(), glCallLists(), and glPopAttrib() func- 
tions, as follows: 


char *s = "Hello, World!"; 


glPushAttrib(GL_LIST_BIT) ; 
glListBase(listbase - ' '); 


glRasterPos3f(@.0f, @.0f, 0.0f); 
glCallLists(strlen(s), GL_BYTE, s); 
glPopAttrib(); 


The example in Listing 14.2 uses this code to draw the names of each side of the cube. 
Figure 14.2 shows the result. 


808 
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Front 


FIGURE 14.2 The Carbon spinning cube with fonts. 
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LISTING 14.2 The CARBONFONTS Sample Program 


/* 
* Include necessary headers... 
*/ 


#include <stdio.h> 
#include <stdlib.h> 
#include <Carbon/Carbon.h> 
#include <AGL/agl.h> 


/* 
* Globals... 
| 
float CubeRotation[3], 
CubeRate[3]; 
int CubeMouseButton, 
CubeMousex, 
CubeMouseY; 
int Cubex, 
CubeY, 
CubeWidth, 
CubeHeight; 
int CubeVisible; 
AGLContext CubeContext; 
GLuint CubeFont; 
/* 
* Functions... 
| 
void DisplayFunc(void) ; 


static pascal OSStatus 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


Rotation of cube */ 

Rotation rate of cube */ 
Button that was pressed */ 
Start X position of mouse */ 
Start Y position of mouse */ 
X position of window */ 

Y position of window */ 
Width of window */ 

Height of window */ 

Is the window visible? */ 
OpenGL context */ 

Display list base for font */ 


EventHandler(EventHandlerCallRef nextHandler, 
EventRef event, void *userData) ; 


void IdleFunc (void) ; 
void MotionFunc(int x, int y); 
void MouseFunc(int button, int state, int x, int y); 


void ReshapeFunc(int width, int height) ; 
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/* 
* ‘'main()' - Main entry for example program. 
“al 
int /* 0 - Exit status */ 
main(int argc, /* I - Number of command-line args */ 
char *argv[]) /* I - Command-line args */ 
{ 
AGLPixelFormat format; /* OpenGL pixel format */ 
WindowPtr window; /* Window */ 
int winattrs; /* Window attributes */ 
Str255 title; /* Title of window */ 
Rect rect; /* Rectangle definition */ 
EventHandlerUPP handler; /* Event handler */ 
EventLoopTimerUPP thandler; /* Timer handler */ 
EventLoopTimerRef timer; /* Timer for animating the window */ 
ProcessSerialNumber psn; /* Process serial number */ 
short font; /* Font number */ 
Str255 fontname; /* Font name */ 
static EventTypeSpec events[] = /* Events we are interested in... */ 
{ 
{ kEventClassMouse, kEventMouseDown }, 
{ kEventClassMouse, kEventMouseUp }, 
{ kEventClassMouse, kEventMouseMoved }, 
{ kEventClassMouse, kEventMouseDragged }, 
{ kEventClassWindow, kEventWindowDrawContent }, 
{ kEventClassWindow, kEventWindowShown }, 
{ kEventClassWindow, kEventWindowHidden }, 
{ kEventClassWindow, kEventWindowActivated }, 
{ kEventClassWindow, kEventWindowDeactivated }, 
{ kEventClassWindow, kEventWindowClose }, 
{ kEventClassWindow, kEventWindowBoundsChanged } 
}; 
static GLint attributes[] = /* OpenGL attributes */ 
{ 
AGL_RGBA, 


AGL_GREEN_SIZE, 1, 
AGL_DOUBLEBUFFER, 
AGL_DEPTH_SIZE, 16, 
AGL_NONE 

}5 
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LISTING 14.2 Continued 


//Set initial values for window 


const int orig“WinHeight = 628; 
const int origWinWidth = 850; 
const int origWinxOffset = 50; 
const int origWinYOffset = 50; 

/* 

* Create the window... 

al | 

CubeContext = Q; 

CubeVisible = Q; 


SetRect(&rect, origWinxOffset, origWinYOffset, origWinWidth, origWinHeight) ; 


winattrs = kWindowStandardHandlerAttribute | kWindowCloseBoxAttribute | 
kWindowCollapseBoxAttribute | kWindowFullZoomAttribute | 
kWindowResizableAttribute | kWindowLiveResizeAttribute; 

winattrs & GetAvailableWindowAttributes (kDocumentWindowClass) ; 


strcpy(title + 1, "Carbon OpenGL Example") ; 
title[®] = strlen(title + 1); 


CreateNewindow(kDocumentWindowClass, winattrs, &rect, &window) ; 
SetWTitle(window, title); 


handler = NewEventHandlerUPP(EventHandler) ; 
InstallWindowEventHandler(window, handler, 

sizeof(events) / sizeof (events[Q]), 

events, NULL, QL); 
thandler = 

NewEventLoopTimerUPP((void (*)(EventLoopTimerRef, void *))IdleFunc) ; 
InstallEventLoopTimer(GetMainEventLoop(), ®, @, thandler, 
@, &timer); 


GetCurrentProcess(&psn) ; 
SetFrontProcess(&psn) ; 


DrawGrowIcon (window) ; 


ShowWindow(window) ; 
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{* 
* Create the OpenGL context and bind it to the window... 
*/ 


format 
CubeContext 


aglChoosePixelFormat(NULL, @, attributes) ; 
aglCreateContext(format, NULL); 


" 


if (!CubeContext) 

{ 
puts("Unable to get OpenGL context!"); 
return (1); 


} 


aglDestroyPixelFormat (format) ; 
aglSetDrawable(CubeContext, GetWindowPort (window) ) ; 


/* 

* Setup remaining globals... 
=/ 

CubeX = 50; 

CubeY = 50; 
CubeWidth = 400; 
CubeHeight = 400; 


CubeRotation[0] = 45.0f; 
CubeRotation[1] = 45.0f; 
CubeRotation[2] = 45.0f; 


CubeRate[Q] = 1.0f; 
CubeRate[1] = 1.0f; 
CubeRate[2] = 1.0f; 
/* 

* Setup font... 

at | 


strcpy(fontname + 1, "Courier New"); 
fontname[@] = strlen(fontname + 1); 


GetFNum(fontname, &font); 


CubeFont = glGenLists(96) ; 
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LISTING 14.2 Continued 
aglUseFont(CubeContext, font, bold, 14, ' ', 96, CubeFont); 


//Set the initial size of the cube 
ReshapeFunc(origWinWidth - origWinxXOffset, origWinHeight - origWinYOffset) ; 


/* 
* Loop forever... 
i | 


for (53) 
{ 
if (CubeVisible) 
SetEventLoopTimerNextFireTime(timer, 0.05); 


RunApplicationEventLoop() ; 


if (CubeVisible) 

{ 
/* 
* Animate the cube... 
Hf 


DisplayFunc(); 
} 
} 
} 


/* 
* 'DisplayFunc()' - Draw a cube. 
sl | 


void 
DisplayFunc(void) 
{ 
int £33 /* Looping vars */ 
float aspectRatio,windowidth, windowHeight; 


static const GLfloat corners[8][3] = /* Corner vertices */ 


{ 
{ 1.0f, 1.0f, 1.0f }, /* Front top right */ 


LISTING 14.2 Continued 


static const int 


static const GLfloat 


/* 


Of, 
Of, 
-1.0f, 
Of, 
Of, -1. 
Of, 
Of, 


BAA AAAS 
ear ‘ 
rag Se eee oe 
' peace 
Re ee 


}5 
sides[6][4] 


colors[6][3] = 

{ 
{ 1.0f, 
{ 0.0f, 
{ 1.0f, 
{ 0.0f, 
{ 1.0f, 
{ 0.0f, 


0.0f, 
1.0f, 
1.0f, 
0.0f, 
0.0f, 
1.0f, 
}5 


* Set the current OpenGL context... 


af 
aglSetCurrentContext(C 
/* 


* Clear the window... 
ef 


ubeContext) ; 


1 
1 
1 
Of, -1.0f 
1 
1 
1 


OF 
OF 
OF 


Of 
-1.0f }, 
Of } 


/* Sides */ 


; 3}; 
pT 
4}, 
, 6 }, 
» 4}; 
» 5} 


/* Colors */ 


0.0f }, 
0.0f }, 
0.0f }, 
1.0f }, 
1.0f }, 
1.0f } 


glViewport(®, @, CubeWidth, CubeHeight) ; 


glClearColor(0.0f, 0.0 
glClear(GL_COLOR_BUFFE 


f, 0.0f, 0.0f); 
R_BIT } 
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/* Front bottom right */ 


/* 
/* 
/* 
/* 
/* 
/* 


j* 
/* 
/* 
/* 
[* 
/* 


f* 
j* 
| pel 
{* 
{* 
/* 


GL_DEPTH_BUFFER_BIT) ; 


Front bottom left */ 
Front top left */ 
Back top right */ 
Back bottom right */ 
Back bottom left */ 
Back top left */ 


Front */ 
Back */ 
Right */ 
Left */ 
Top */ 
Bottom */ 


Red */ 
Green */ 
Yellow */ 
Blue */ 
Magenta */ 
Cyan */ 
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LISTING 14.2 Continued 
/* 
* Setup the matrices... 
*/ 


glMatrixMode(GL_PROJECTION) ; 

glLoadIdentity(); 
aspectRatio = (GLfloat)CubeWidth / (GLfloat)CubeHeight; 
if (CubeWidth <= CubeHeight) 


{ 

windowidth = 2.0f; 

windowHeight = 2.0f / aspectRatio; 

glOrtho(-2.0f, 2.0f, -windowHeight, windowHeight, 2.0f, -2.0f); 
} 
else 
{ 

windowidth = 2.0f * aspectRatio; 

windowHeight = 2.0f; 

glOrtho(-windowHeight, windowHeight, -2.0f, 2.0f, 2.0f, -2.0f); 
} 


glMatrixMode(GL_MODELVIEW) ; 

glLoadidentity(); 

glRotatef(CubeRotation[®], 1.0f, 0.0f, 0.0f); 
glRotatef(CubeRotation[1], 0.0f, 1.0f, 0.0f); 
glRotatef(CubeRotation[2], 0.0f, 0.0f, 1.0f); 


/* 
* Draw the cube... 
*/ 


glEnable(GL_DEPTH_TEST) ; 
g1Begin(GL_QUADS) ; 


for (1 = 03 i < 63. i ++) 
{ 
glColor3fv(colors[i]); 
at) A a ie a i 
glVertex3fv(corners[sides[i][j]]); 


LISTING 14.2 Continued 
glEnd(); 


/* 
* Draw lines coming out of the cube... 
ll | 


glColor3f(1.0f, 1.0f, 1.0f); 


glBegin(GL_LINES) ; 
glVertex3f(0.0f, 0.0f, -1.5f); 
glVertex3f(0.0f, @.0f, 1.5f); 


glVertex3f(-1.5f, 0.0f, 0.0f); 
glVertex3f(1.5f, @.0f, 0.0f); 


glVertex3f(0.0f, 1.5f, 0.0f); 
glVertex3f(0.0f, -1.5f, @.Of); 
glEnd(); 


/* 
* Draw text for each side... 
“al | 


glPushAttrib(GL_LIST_BIT) ; 
glListBase(CubeFont - ' '); 


glRasterPos3f(0.0f, @.0f, -1.5f); 
glCallLists(4, GL_BYTE, "Back"); 


glRasterPos3f(@.0f, 0.0f, 1.5f); 
glCallLists(5, GL_BYTE, "Front"); 


glRasterPos3f(-1.5f, @.0f, 0.0f); 
glCallLists(4, GL_BYTE, "Left"); 


glRasterPos3f(1.5f, 0.0f, @.0f); 
glCallLists(5, GL_BYTE, “Right"); 


glRasterPos3f(@.0f, 1.5f, 0.0f); 
glCallLists(3, GL_BYTE, "Top"); 
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LISTING 14.2 Continued 


glRasterPos3f(0.0f, -1.5f, 0.0f); 
glCallLists(6, GL_BYTE, "Bottom") ; 
glPopAttrib(); 


/* 
* Swap the front and back buffers... 
ay 


aglSwapBuffers(CubeContext) ; 


} 
/* 
* 'EventHandler()' - Handle window and mouse events from the window manager. 
wf 
static pascal OSStatus /* 0 - noErr on success or error code */ 
EventHandler(EventHandlerCallRef nextHandler, /* I - Next handler to call */ 
EventRef event, /* I - Event reference */ 
void *userData) /* I - User data (not used) */ 
{ 
UInt32 kind; /* Kind of event */ 
Rect rect; /* New window size */ 
EventMouseButton button; /* Mouse button */ 
Point point; /* Mouse position */ 


kind = GetEventKind(event) ; 


if (GetEventClass(event) == kEventClassWindow) 
{ 
switch (kind) 
{ 
case kEventWindowDrawContent : 
if (CubeVisible && CubeContext) 
DisplayFunc(); 
break; 


case kEventWindowBoundsChanged : 
GetEventParameter(event, kEventParamCurrentBounds, typeQDRectangle, 
NULL, sizeof(Rect), NULL, &rect); 
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CubeX = rect.left; 
CubeY = rect.top; 


if (CubeContext) 
aglUpdateContext (CubeContext) ; 


ReshapeFunc(rect.right - rect.left, rect.bottom - rect.top); 


if (CubeVisible && CubeContext) 
DisplayFunc(); 
break; 


case kEventWindowShown : 
CubeVisible = 1; 
if (CubeContext) 
DisplayFunc(); 
break; 


VL 


case kEventWindowHidden : 
CubeVisible = 0; 
break; 


case kEventWindowClose : 


ExitToShell(); 
break; 
} 
} 
else 
{ 
switch (kind) 
{ 


case kEventMouseDown : 
GetEventParameter(event, kEventParamMouseButton, typeMouseButton, 
NULL, sizeof(EventMouseButton), NULL, &button); 
GetEventParameter(event, kEventParamMouseLocation, typeQDPoint, 
NULL, sizeof(Point), NULL, &point); 


if (point.v < CubeyY |} 
(point.v > (CubeY + CubeHeight - 8) && 
point.h > (CubeX + CubeWidth - 8))) 
return (CallNextEventHandler(nextHandler, event)); 
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LISTING 14.2 Continued 


MouseFunc(button, @, point.h, point.v); 
break; 


case kEventMouseUp : 
GetEventParameter(event, kEventParamMouseButton, typeMouseButton, 
NULL, sizeof(EventMouseButton), NULL, &button); 
GetEventParameter(event, kEventParamMouseLocation, typeQDPoint, 
NULL, sizeof(Point), NULL, &point); 


if (point.v < CubeY |} 
(point.v > (CubeY + CubeHeight - 8) && 
point.h > (CubeX + CubeWidth - 8))) 
return (CallNextEventHandler(nextHandler, event)); 


MouseFunc(button, 1, point.h, point.v); 
break; 


case kEventMouseDragged : 
GetEventParameter(event, kEventParamMouseLocation, typeQDPoint, 
NULL, sizeof(Point), NULL, &point); 


if (point.v < CubeY |} 
(point.v > (CubeY + CubeHeight - 8) && 
point.h > (CubeX + CubeWidth - 8))) 
return (CallNextEventHandler(nextHandler, event)); 


MotionFunc(point.h, point.v); 
break; 


default : 
return (CallNextEventHandler(nextHandler, event)); 


[* 
* Return whether we handled the event... 
| 


return (noErr); 


} 
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LISTING 14.2 Continued 

/* 

* ‘IdleFunc()' - Rotate and redraw the cube. 
si 


void 

IdleFunc(void) 

{ 
CubeRotation[0] += CubeRate[Q]; 
CubeRotation[1] += CubeRate[1]; 
CubeRotation[2] += CubeRate[2]; 


QuitApplicationEventLoop() ; 


} 
/* 
* 'MotionFunc()' - Handle mouse pointer motion. 
it 
void 
MotionFunc(int x, /* I - X position */ 
int y) /* I - Y position */ 
{ 
/* 
* Get the mouse movement... 
set 
= CubeMousex; 
= CubeMouseyY; 
/* 


* Update the cube rotation rate based upon the mouse movement and 
* DPUETON:. << 
mh 


switch (CubeMouseButton) 


{ 
case 0: /* Button 1 */ 
CubeRate[0] = 0.01f * y; 
CubeRate[1] = @.01f * x; 
CubeRate[2] = 0.0f; 


break; 
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LISTING 14.2 Continued 


case 1: /* Button 2 */ 
CubeRate[0] = 0.0f; 
CubeRate[1] = 0.01f * y; 
CubeRate[2] = 0.01f * x; 
break; 
default : /* Button 3 */ 
CubeRate[Q] = 0.01f * y; 
CubeRate[1] = 0.0f; 
CubeRate[2] = @.01f * x; 
break; 
} 
} 
/* 
* 'MouseFunc()' - Handle mouse button press/release events. 
*/ 
void 
MouseFunc(int button, /* I - Button that was pressed */ 
int state, /* I - Button state (@ = down) */ 
int x, /* I - X position */ 
int y) /* I - Y position */ 
{ 
/* 
* Only respond to button presses... 
*/ 
if (state) 
return; 
/* 
* Save the mouse state... 
*/ 
CubeMouseButton = button; 
CubeMouseX = X; 
CubeMouseY = y;3 
j* 


* Zero-out the rotation rates... 


Using the Cocoa API 


LISTING 14.2 Continued 


*/ 

CubeRate[0] = 0.0f; 
CubeRate[1] = 0.0f; 
CubeRate[2] = 0.0f; 


} 


/* 
* 'ReshapeFunc()' - Resize the window. 


*/ 
void 
ReshapeFunc(int width, /* I - Width of window */ 
int height) /* I - Height of window */ 
{ 
CubeWidth = width; 
CubeHeight = height; 
} 


Using the Cocoa API 


The Cocoa API is suitable for applications developed using Objective C and the Cocoa user 
interface classes. Cocoa provides a single OpenGL rendering class that you must subclass 
to do OpenGL rendering. 


Cocoa programs of this type require the ApplicationServices, Cocoa, and OpenGL frame- 
works; you can start with a Cocoa-based application in the project builder application and 
add the OpenGL framework or use the following linker options: 


-framework Cocoa -framework OpenGL -framework ApplicationServices 


The NSOpenGL Class 

The NSOpenGL class provides the basis for all OpenGL-based Cocoa components. You must 
subclass this class to implement a Cocoa-based OpenGL display, implementing three 
required methods: basicPixelFormat, drawRect, and initWithFrame. The 
basicPixelFormat method is used to create a copy of an attribute array similar to that 
used by the aglChoosePixelFormat function. The following code shows a typical imple- 
mentation that requests a double-buffered pixel format with at least 16 bits of depth 
buffer: 


775 


VL 


776 


CHAPTER 14 OpenGL on MacOS X 


+ (NSOpenGLPixelFormat*) basicPixelFormat 
{ 
static NSOpenGLPixelFormatAttribute attributes[] = 
{ 
NSOpenGLPFAWindow, 
NSOpenGLPFADoubleBuffer, 
NSOpenGLPFADepthSize, (NSOpenGLPixelFormatAttribute) 16, 
(NSOpenGLPixelFormatAttribute)nil 


}5 


return ([[[NSOpenGLPixelFormat alloc] initWithAttributes] autoRelease]) ; 
} 


Each attribute value is of type NSOpenGLPixelFormatAttribute and the attribute list is 
terminated by a nil (zero) value. Table 14.3 lists the valid attribute values. 


TABLE 14.3 NSOpenGLPixelFormatAttribute Constants 


Constant Description 

NSOpenGLPFAAccelerated This constant specifies that a hardware-accelerated pixel format is 
required. 

NSOpenGLPFAAccumAlphaSize The number that follows specifies the minimum number of alpha 
bits that are required in the accumulation buffer. 

NSOpenGLPFAAccumBlueSize The number that follows specifies the minimum number of blue 
bits that are required in the accumulation buffer. 

NSOpenGLPFAAccumGreenSize The number that follows specifies the minimum number of green 
bits that are required in the accumulation buffer. 

NSOpenGLPFAAccumRedSize The number that follows specifies the minimum number of red bits 
that are required in the accumulation buffer. 

NSOpenGLPFAAlphaSize The number that follows specifies the minimum number of alpha 
bits that are required. 

NSOpenGLPFAAuxBuf fers The number that follows specifies the number of auxiliary buffers 
that are required. 

NSOpenGLPFABackingStore This constant specifies that only formats that support a full backing 
store capability should be used. 

NSOpenGLPFABlueSize The number that follows specifies the minimum number of blue 
bits that are required. 

NSOpenGLPFABufferSize The number that follows specifies the number of color index bits 
that are desired. 

NSOpenGLPFAClosestPolicy This constant specifies that the sizes specified should be used as 


the ideal requirements for the pixel format, and the pixel format 
should use the closest number of bits possible. 
NSOpenGLPFADepthSize The number that follows specifies the minimum number of depth 
bits that are required. 
NSOpenGLPFADoubleBuffer This constant specifies that a double-buffered visual is desired. 


Constant 


NSOpenGLPFAGreenSize 


NSOpenGLPFALevel 


NSOpenGLPFAMinimumPolicy 


NSOpenGLPFAMaximumPolicy 


NSOpenGLPFAOffScreen 


NSOpenGLPFAPixelSize 


NSOpenGLPFARedSize 


NSOpenGLPFAStencilSize 


NSOpenGLPFAStereo 
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Description 


The number that follows specifies the minimum number of green 
bits that are required. 

This constant specifies the buffer level in the number that follows; 
0 is the main buffer, 1 is the first overlay buffer, —1 is the first 
underlay buffer, and so forth. 

This constant specifies that the sizes specified should be used as 
the minimum requirements for the pixel format, and the pixel 
format should use the minimum number of bits possible. 

This constant specifies that the sizes specified should be used as 
the minimum requirements for the pixel format, and the pixel 
format should use the maximum number of bits possible. 

This constant specifies that the pixel format is for an offscreen 
buffer. 

The number that follows specifies the total number of bits that are 
used for a pixel. 

The number that follows specifies the minimum number of red bits 
that are required. 

The number that follows specifies the minimum number of stencil 
bits that are required. 

This constant specifies that a stereo visual is desired; stereo visuals 
provide separate left and right eye images. 


The drawRect method does any OpenGL drawing calls to redraw the widget; the rect 
argument can be used to set the viewport and viewing transformation as necessary: 


- (void)drawRect: (NSRect)rect 


int width, height; 


// Get the current bounding rectangle... 


width = rect.size.width; 
height = rect.size.height; 


// Set the viewport... 


glViewport(®, ®, width, height); 


// Setup the projection matrix... 


glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 
glOrtho(-2.0f, 2.0f, 


-2.0f * height / width, 2.0f * height / width, 


-2.0f, 2.0f); 
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// Call any OpenGL functions to draw the scene... 


Finally, the initWithFrame method initializes the OpenGL drawing area: 


- (id)initWithFrame: (NSRect) frameRect 
NSOpenGLPixelFormat *pf; 
// Get the pixel format and return a new window from it... 


pf [MyClass basicPixelFormat]; 
self = [super initWithFrame: frameRect pixelFormat: pf]; 


return (self); 


The NSOpenGL class handles the creation of an OpenGL context for use with the pixel 
format that you have supplied. 


Your First Cocoa Program 


Now that we have covered the basics of using the NSOpenGL class for Cocoa applications, 
we will convert the Carbon Cube example to Cocoa. All the Carbon code is fully 
contained in a class called Cube that is based on NSOpenGL and implements all the required 
methods described in the previous section. It also implements the mouse methods so that 
you can click and drag the mouse to rotate the cube. Listing 14.3 shows the completed 
Cocoa application that displays a spinning cube. The results are shown in Figure 14.3. 


e208 Window 


FIGURE 14.3. The COCOACUBE program. 
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LISTING 14.3 The cocoa.m Sample Program 


#import <Cocoa/Cocoa.h> 
#import <Carbon/Carbon.h> 
#import <OpenGL/gl.h> 
#import <OpenGL/glext.h> 
#import <OpenGL/glu.h> 


// Interface definition for our NIB CustomView 
// In the NIB builder, derive as subclass named 
// Cube from NSOpenGLView. Then assign this to a 
// customview that fills the window. 

@interface Cube : NSOpenGLView 


{ 

bool initialized; 

NSTimer *timer; 

float rotation[3], 

rate[3]; 
int mouse_xX, 
mouse_y; 

GLuint font; 

} 
@end 
// 
// ‘main()' - Main entry for program. 
// 
int // 0 - Exit status 
main(int argc, // I - Number of command-line args 

const char *argv[]) // I - Command-line arguments 
{ 

return (NSApplicationMain(argc, argv)); 

} 
// 
// Cube class based upon NSOpenGLView 
// 


@implementation Cube : NSOpenGLView 

€ 
bool initialized; // Are we initialized? 
NSTimer *timer; // Timer for animation 
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LISTING 14.3 Continued 


float rotation[3], // Rotation of cube 
rate[3]; // Rotation rate of cube 
int mouse_x, // Start X position of mouse 
mouse_y; // Start Y position of mouse 
} 
// 
// ‘basicPixelFormat()' - Set the pixel format for the window. 
// 


+ (NSOpenGLPixelFormat*) basicPixelFormat 
{ 
static NSOpenGLPixelFormatAttribute attributes[] = // OpenGL attributes 
{ 
NSOpenGLPFAWindow, 
NSOpenGLPFADoubleBuffer, 
NSOpenGLPFADepthSize, (NSOpenGLPixelFormatAttribute) 16, 
(NSOpenGLPixelFormatAttribute) nil 
}; 


return ([[[NSOpenGLPixelFormat alloc] initWithAttributes:attributes]autorelease] ) ; 


// 
// ‘'resizeGL()' - Resize the window. 
// 


- (void) resizeGL 
{ 
} 


// 
// ‘idle()' - Update the display using the current rotation rates... 
// 


- (void)idle:(NSTimer *)timer 
{ 
// Rotate... 
rotation[0] += rate[Q]; 
rotation[1] += rate[1]; 
rotation[2] += rate[2]; 
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LISTING 14.3 Continued 

// Redraw the window... 

[self drawRect:[self bounds] ]; 
} 


// 
// ‘mouseDown()' - Handle left mouse button presses... 
// 


- (void)mouseDown: (NSEvent *)theEvent 
NSPoint point; // Mouse position 
// Get and save the mouse position 
point = [self convertPoint:[theEvent locationInWindow] fromView:nil]; 


mouse_X = point.x; 
mouse_y = point.y; 


// Null the rotation rates... 
rate[0] = 0.0f; 
rate[1] Q.0Ff; 
rate[2] = 0.0f; 


// 
// ‘rightMouseDown()' - Handle right mouse button presses... 


// 


- (void) rightMouseDown: (NSEvent *)theEvent 


{ 
NSPoint point; // Mouse position 


// Get and save the mouse position 

point = [self convertPoint:[theEvent locationInWindow] fromView:nil]; 
mouse_X = point.x; 

mouse_y = point.y; 


// Null the rotation rates... 
rate[@] = 0.0f; 
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LISTING 14.3 Continued 


rate[1] = 0.0f; 


rate[2] = 0.0f; 
} 
// 
// ‘otherMouseDown()' - Handle middle mouse button presses... 
// 
- (void) otherMouseDown: (NSEvent *)theEvent 
{ 
NSPoint point; // Mouse position 


// Get and save the mouse position 

point [self convertPoint:[theEvent locationInWindow] fromView:nil]; 
mouse_X = point.x; 

mouse_y = point.y; 


// Null the rotation rates... 


rate[O] = 0.0f; 
rate[1] = 0.0f; 
rate[2] = 0.0f; 
} 
// 
// ‘mouseDragged()' - Handle drags using the left mouse button. 
// 
- (void)mouseDragged: (NSEvent *)theEvent 
{ 
NSPoint point; // Mouse position 


// Get the mouse position and update the rotation rates... 

point = [self convertPoint:[theEvent locationInWindow] fromView: nil]; 
rate[0] = 0.01f * (mouse_y - point.y); 

rate[1] = 0.01f * (mouse_x - point.x); 
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LISTING 14.3 Continued 


// 
// ‘rightMouseDragged()' - Handle drags using the right mouse button. 
// 


- (void) rightMouseDragged: (NSEvent *)theEvent 
{ 
NSPoint point; // Mouse position 


// Get the mouse position and update the rotation rates... 
point = [self convertPoint:[theEvent locationInWindow] fromView:nil]; 


rate[@] = 0.01f * (mouse_y - point.y); 

rate[2] = 0.01f * (mouse_x - point.x); 1 
} + 
// 
// ‘otherMouseDragged()' - Handle drags using the middle mouse button. 
// 


- (void)otherMouseDragged: (NSEvent *)theEvent 


NSPoint point; // Mouse position 


// Get the mouse position and update the rotation rates... 

point = [self convertPoint:[theEvent locationInWindow] fromView:nil]; 
rate[1] @.01f * (mouse_y - point.y); 

rate[2] @.01f * (mouse_x - point.x); 


- (void) drawRect: (NSRect) rect 


{ 
int width, // Width of window 
height; // Height of window 
int 5 a fi // Looping vars 
float aspectRatio, windowidth, windowHeight; 
static const GLfloat corners[8][3] = // Corner vertices 
{ 


{ -40f 5... 120f,, Gf 3, // Front top right 
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LISTING 14.3 Continued 


static const int 


static const GLfloat colors[6][3] = 


Of, 
Of, 
Of, >= 
-1.0f, - 
-1.0f, 


SBA AAAS 
‘ 
PR ek ky eek ee ee 


}5 
sides[6][4] 
{ 


}5 


{ 

1.0f, 
0.0f, 
1.0f, 
0.0f, 
1.0f, 
0.0f, 


RAMA A AS 
-esecs--+- 9 


}3 


Of, - 
1het, % 


// Set the current OpenGL context.. 
if (l!initialized) 


‘ 


rotation[0] 
rotation[1] 
rotation[2] 
rate[0] 
rate[1] 
rate[2] 
initialized 


45.0f; 
45.0f; 
45.0f; 
1.0f; 
1.0f; 
1.0f; 
true; 


1.0f, 1.0f }, 
15 OF57 11 OF 45 
1.0f, 1.0f }, 
1.0f, -1.0f }, 
1.0 ;*+1.0F }, 
1.Of, -1.0f }, 
1.0f, -1.0f } 
= // Sides 

3}, 

7 }s 

4}, 

6 }, 

4}, 

5 } 

= // Colors 
Of, O.OF }, 
Of, O.OFf }, 
Of, O.O0f }, 
OF, 1.0f }, 
Of, 1.0f }, 
Of, 1.0f } 


// 
// 
// 
// 
// 
// 
// 


// 
// 
// 
// 
// 
// 


// 
// 
// 
// 
// 
// 


Front bottom right 
Front bottom left 
Front top left 
Back top right 
Back bottom right 
Back bottom left 
Back top left 


Front 
Back 
Right 
Left 
Top 
Bottom 


Red 
Green 
Yellow 
Blue 
Magenta 
Cyan 
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LISTING 14.3 Continued 


// Use the current bounding rectangle for the cube window... 
width = rect.size.width; 
height = rect.size.height; 


// Clear the window... 

glViewport(®, ®, width, height); 

glClearColor(0.0f, 0.0f, @.0f, 0.0f); 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


// Setup the matrices... 
glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 


aspectRatio = (GLfloat)width / (GLfloat)height; 
if (width <= height) 


{ 
windowidth = 2.0f; 
windowHeight = 2.0f / aspectRatio; 
glOrtho(-2.0f, 2.0f, -windowHeight, windowHeight, 2.0f, -2.0f); 
} 
else 
{ 
windowidth = 2.0f * aspectRatio; 
windowHeight = 2.0f; 
glOrtho(-windowHeight, windowHeight, -2.0f, 2.0f, 2.0f, -2.0f); 
} 
glMatrixMode(GL_MODELVIEW) ; 
glLoadIdentity(); 


glRotatef(rotation[®], 1.0f, 0.0f, 0.0f); 
glRotatef(rotation[1], 0.0f, 1.0f, 0.0f); 
glRotatef(rotation[2], 0.0f, 0.0f, 1.0f); 


// Draw the cube... 
glEnable(GL_DEPTH_TEST) ; 


glBegin(GL_QUADS) ; 
Toni. tossed e+) 


{ 
glColor3fv(colors[i]); 
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LISTING 14.3 Continued 


for (j = 0; j < 4; j ++) 
glVertex3fv(corners[sides[i][j]]); 


glEnd(); 


// Draw lines coming out of the cube... 
glColor3f(1.0f, 1.0f, 1.0f); 


glBegin(GL_LINES) ; 
glVertex3f(0.0f, @.0f, -1.5f); 
glVertex3f(@.0f, @.0f, 1.5f); 


glVertex3f(-1.5f, @.0f, 0.0f); 
glVertex3f(1.5f, 0.0f, 0.0f); 


glVertex3f(0.0f, 1.5f, 0.0f); 
glVertex3f(0.0f, -1.5f, 0.0f); 
glEnd(); 


// Swap the front and back buffers... 
[[self openGLContext]flushBuffer]; 
} 


// 
// ‘acceptsFirstResponder()' ... 
// 


- (BOOL)acceptsFirstResponder 
{ 

return (YES); 
} 


- (BOOL) becomeFirstResponder 


{ 
return (YES); 


} 
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LISTING 14.3 Continued 


- (BOOL) resignFirstResponder 


{ 
return (YES); 
} 
iif 
// ‘initWithFrame()' - Initialize the cube. 
// 


- (id) initWithFrame: (NSRect)frameRect 
{ 
NSOpenGLPixelFormat *pf; 


// Get the pixel format and return a new cube window from it... 
pf [Cube basicPixelFormat]; 
self [super initWithFrame: frameRect pixelFormat: pf]; 


return (self); 


// 


// ‘awakeFromNib()' - Do stuff once the UI is loaded from the NIB file... 
// 


- (void) awakeFromNib 

{ 
// Set initial values... 
initialized = false; 


//start cube rotating 
{self drawRect:[self bounds] ]; 
// Start the timer running... 
timer = [NSTimer timerWithTimeInterval:(@.05f) target:self 
selector:@selector(idle:) userInfo:nil repeats: YES]; 
{{NSRunLoop currentRunLoop]addTimer: timer forMode:NSDefaultRunLoopMode] ; 
{{NSRunLoop currentRunLoop]addTimer:timer forMode:NSEventTrackingRunLoopMode] ; 
} 


@end 
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Summary 


OpenGL is well supported on MacOS X and can be accessed using several different APIs 
provided by Apple: AGL, CGL, Cocoa, and GLUT. The AGL API provides OpenGL support 
for Carbon-based applications and is supported on MacOS 8 through X, the CGL API 
provides full-screen OpenGL support and is meant for use with games and other full- 
screen applications, the Cocoa API is an Objective C interface for complex GUIs that 
include OpenGL-based components, and the GLUT API provides a simple, cross-platform 
interface for the sample programs in this book as well as for simple applications. 


Reference 


agiChoosePixelFormat 


Purpose: Enables you to choose a pixel format for OpenGL rendering. 
Include File: <AGL/agl.h> 
Syntax: 


AGLPixelFormat aglChoosePixelFormat(const AGLDevice *gdevs, GLint ndev, const GLint 
*attribs) ; 


Description: This function locates a compatible pixel format for all the listed devices. 
If ndev is 0, a pixel format is chosen that is compatible with all display 
devices. 

Parameters: 

*gdevs const AGLDevice: An array of graphics devices. 

ndev GLint: The number of graphics devices. 

*attribs const GLint: An array of integer attributes terminated by the AGL_NONE 
constant. 

Returns: A compatible pixel format or NULL if no pixel format satisfies the speci- 
fied attributes. 

See Also: aglCreateContext 

agiCreateContext 

Purpose: Creates an OpenGL context for rendering. 

Include File: <AGL/agl.h> 

Syntax: 


AGLContext aglCreateContext(AGLPixelFormat pix, AGLContext share) ; 


Reference 


Description: This function creates a new OpenGL rendering context. If the share argu- 
ment is not NULL, the new context will share display lists, texture objects, 
and vertex arrays with the specified context. 


Parameters: 

pix AGLPixelFormat: The pixel format to use, as returned by 
aglChoosePixelFormat. 

share AGLContext: The OpenGL context to share with or NULL. 

Returns: A new OpenGL context or NULL if it could not be created. 

See Also: aglChoosePixelFormat, aglDestroyContext, aglSetCurrentContext, 
aglSetDrawable 

ag|DestroyContext 

Purpose: To destroy an OpenGL rendering context. 

Include File: <AGL/agl.h> 

Syntax: 


GLboolean aglDestroyContext(AGLContext ctx); 


Description: This function destroys the specified OpenGL context. 


Parameters: 

ctx AGLContext: The OpenGL context to destroy. 

Returns: GL_FALSE if the context could not be destroyed; GL_TRUE otherwise. 
See Also: aglCreateContext 

aglSetCurrentContext 

Purpose: Sets the current context for OpenGL rendering. 

Include File: <AGL/agl.h> 

Syntax: 


GLboolean aglSetCurrentContext(AGLContext ctx); 


Description: This function sets the current OpenGL context for rendering. 
Parameters: 

ctx AGLContext: The OpenGL context to use. 

Returns: GL_FALSE if the context could not be used; GL_TRUE otherwise. 


See Also: aglCreateContext, aglSetDrawable 
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aglSetDrawable 


Purpose: 
Include File: 
Syntax: 


Sets the window or offscreen buffer associated with a context. 
<AGL/agl.h> 


GLboolean aglSetDrawable(AGLContext ctx, AGLDrawable draw) ; 


Description: 


This function binds a window or offscreen buffer to an OpenGL context. 
You must call this function after creating the context and before using 
the context to do any rendering. 


Parameters: 

ctx AGLContext: The OpenGL context to bind. 

draw AGLDrawable: The window or offscreen buffer to use. 

Returns: GL_FALSE if the drawable could not be bound; GL_TRUE otherwise. 
See Also: aglCreateContext, aglSetCurrentContext 

ag!SwapBuffers 

Purpose: Swaps the front and back buffers in an OpenGL window. 


Include File: 
Syntax: 


<AGL/agl.h> 


void aglSwapBuffers(AGLContext ctx); 


Description: 


Parameters: 
ctx 
Returns: 
See Also: 


aglUseFont 
Purpose: 
Include File: 
Syntax: 


This function swaps the front and back buffers of the double-buffered 
OpenGL window bound to the specified context. You typically call this 
function after drawing a scene or frame using OpenGL functions. 


AGLContext: The OpenGL context to swap. 
Nothing 
aglCreateContext 


Creates a collection of bitmap display lists. 
<AGL/agl.h> 


GLboolean aglUseFont(AGLContext ctx, GLint fontID, Style face, GLint size, int 
first, int count, int base); 


Description: 


Parameters: 


ctx 
fontID 
face 
size 
first 
count 
base 
Returns: 
See Also: 


Reference 791 


This function creates count display lists containing bitmaps of characters 
in the specified font. You allocate the display lists for the bitmaps using 
the glGenLists function. 


AGLContext: Specifies the current rendering context. 

GLint: Specifies the font to use. 

Style: Specifies the font style to use. 

GLint: Specifies the size of font to use. 

int: Specifies the first character in the font to use. 

int: Specifies the number of characters to use from the font. 

int: Specifies the first display list to use as returned by glGenLists 
GL_TRUE if successful; GL_FALSE otherwise 

aglCreateContext 
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CHAPTER 15 
GLX: OpenGL on Linux 


by Nick Haemel 

WHAT YOU’LL LEARN IN THIS CHAPTER: 

How To Functions You'll Use 

Choose appropriate visuals for g1XChooseVisual, g1XChooseFBConf ig 

Manage OpenGL drawing contexts glXCreateContext, glxDestroyContext, glXMakeCurrent 

Create OpenGL windows glXCreateWindow 

Do double-buffered drawing glXSwapBuf fers 

Create bitmap text fonts g1XUseXFont 

Do offscreen drawing g1XCreateGLXPixmap, g1XCreatePbuffer 


This chapter discusses GLX, the OpenGL extension that is used to support OpenGL appli- 
cations through the X Window System on UNIX and Linux. You learn how to create and 
manage OpenGL contexts as well as how to create OpenGL drawing areas with several of 
the common GUI toolkits. You also learn how to use GLUT with all the examples in this 

book. 


The Basics 


OpenGL on UNIX and Linux uses the OpenGL extension to the X Window System called 
GLX. All GLX-specific functions start with the prefix g1X and are generally included in the 
GL library. The GLX functions are the “glue” binding OpenGL, X11, and the graphics 
hardware that provides accelerated rendering. 


Using the OpenGL and X11 Libraries 


The location of the OpenGL and X11 libraries and header files varies from system to 
system. Some are in the standard include and library locations, such as /usr/include and 
/usr/lib, that require only the libraries with the link command: 


gcc -o myprogram myprogram.o -1GLU -1GL -1Xext -1X11 -1lm 
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Others use a version-specific location, such as /usr/X11R6/include or /usr/X11R6/1ib, 
that requires both compiler and linker options: 


gcc -I/usr/X11R6/include -c myprogram.c 
gcc -O myprogram myprogram.o -L/usr/X11R6/lib -1GLU -1GL -1Xext -1X11 -1m 


You can hard-code the compiler and linker options if you are writing an application for a 
single platform; however, most OpenGL applications see life on many different platforms, 
so you might want to detect the appropriate options prior to doing a build. One common 
method is to use the GNU autoconf software to create a configure script that initializes 
your options for you. Listing 15.1 provides a sample configure. in file for use with 
autoconf. 


LISTING 15.1 Sample configure. in File for GNU autoconf 


dnl Required file in package... 
AC_INIT(myprogram.c) 


dnl Find the C compiler... 
AC_PROG_CC 


dnl Find the X Window System... 
AC_PATH_XTRA 


LIBS="$LIBS -1Xext -1X11 $X_EXTRA_LIBS" 
CFLAGS="$CFLAGS $X_CFLAGS" 
LDFLAGS="$X_LIBS $LDFLAGS" 


if test "x$x_includes" != x; then 
ac_cpp="$ac_cpp -I$x_includes" 
tz 


dnl OpenGL uses the math functions... 
AC_SEARCH_LIBS(pow, m) 


dnl Some OpenGL implementations use dlopen()... 
AC_SEARCH_LIBS(dlopen, dl) 


dnl Look for the OpenGL or Mesa libraries... 
AC_CHECK_HEADER(GL/g1.h) 
AC_CHECK_HEADER(GL/glu.h) 
AC_CHECK_HEADER(GL/g1x.h) 


AC_CHECK_LIB(GL, glXMakeCurrent, 


LISTING 15.1 Continued 


LIBS="-1GLU -1GL $LIBS", 
AC_CHECK_LIB(MesaGL, glXMakeCurrent, 
LIBS="-1MesaGLU -1lMesaGL $LIBS") ) 


dnl Generate a Makefile for the program 


The Basics 


AC_OUTPUT (Makefile) 


You build the actual configure script using the following command: 


autoconf 


The AC_PATH_XTRA and AC_CHECK_LIB macros handle searching for the X11 and OpenGL 
libraries, and the AC_OUTPUT macro generates any files using what the script found. The 


Makefile.in file used by the configure script is shown in Listing 15.2. 


LISTING 15.2 Makefile Template File Makefile.in 


# 


# Sample makefile template for configure script. 


# 


# 
# Compiler and options... 
# 


cc = @cce@ 

CFLAGS = @CFLAGS@ 
LDFLAGS = @LDFLAGS@ 
LIBS = @LIBS@ 

# 

# Program 

# 

myprogram: myprogram.o 


$(CC) $(LDFLAGS) -o myprogram myprogram.o $(LIBS) 


The configure script substitutes the variables specified in Makefile.in to produce the 
final makefile to build your application. You specify variables using an at sign (@) before 
and after the variable name, such as @CC@ for the C compiler, @CFLAGS@ for the compiler 


options, and so forth. 
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You run the configure script to generate the makefile and then use the make command to 
build your program, as follows: 


./configure 
make 


You can use this same technique to create include files for makefiles to include common 
compiler and linker options for larger, multiple-directory projects, or you can list multiple 
makefile templates in the AC_OUTPUT macro. 


A variation of the configure.in and Makefile.in files is used to build all the examples in 
this book on UNIX and Linux. 


Using the GLUT Library 

The GLUT library is not generally provided as a standard part of UNIX or Linux distribu- 
tions; however, it is available as source code and can be compiled and installed relatively 
easily from the source that comes on the CD-ROM. Start by copying the glut -3.7 direc- 
tory to your own hard drive. Then run the following commands: 


cd glut-3.7 
./mkmkfiles.imake 
make 

make install 


After you install GLUT, simply add the GLUT library to your link command: 


gcc -O myprogram myprogram.o -lglut -1GLU -1GL -1Xext -1X11 -lm 


Or add it to your makefile template: 


LIBS = -lglut @LIBS@ 


OpenGL on Linux 


Although most commercial versions of UNIX provide OpenGL support out of the box, 
OpenGL support on Linux depends greatly on the graphics card and Linux distribution 
you use. Also, there are both free and commercial versions of OpenGL that you can use. 


The Xfree86 project provides the most popular free implementation of the X Window 
System and is provided with every Linux distribution. Xfree86 4.x uses the Direct 
Rendering Infrastructure (DRI) to provide accelerated OpenGL rendering. The following 
URLs provide information on each of these projects: 


http://www. xfree86.org/ 
http: //dri.sf.net/ 


The OpenGL Extension for the X Window System 


OpenGL support is enabled through the XF86Config or XF86Config-4 file, usually installed 
in /etc/X11. The key area of this file is the Module section, which follows: 


Section "Module" 
Load "GLcore" # OpenGL support 
Load "glx" # OpenGL X protocol interface 
Load "dri" # Direct rendering infrastructure 


The Load lines load the named modules—GLcore, glx, and dri—and those modules 
provide OpenGL support. If the underlying driver supports OpenGL, your output will be 
hardware accelerated. Otherwise, software emulation is used. 


Commercial implementations of the X Window System are also available. One popular 
package that provides strong OpenGL support is Summit from Xi Graphics, available at 
the following URL: 


http: //www.xi-graphics.com/ 


OpenGL Emulation: Mesa 

The Mesa library can be used on systems that don’t support OpenGL natively, when you 
want to experiment with new OpenGL features or extensions that are not supported by 
your graphics card, or when you want to do offline rendering using OpenGL. You can find 
the Mesa library at the following URL: 


http://mesa3d.sf.net/ 


Aside from its use as a standalone library, Mesa also serves as the core of the Xfree86 
implementation of OpenGL. 


The OpenGL Extension for the X Window System 


The OpenGL extension for the X Window System, GLX, provides the interface between 
your application, the X Window System, and the graphics driver to provide accelerated 
rendering. If the underlying graphics hardware does not support a particular feature, it is 
automatically emulated in software. You can check whether your X server supports this 
extension by using the xdpyinfo program on the command line: 


xdpyinfo | grep GLX 
There have been five versions of the GLX extension to date (1.0, 1.1, 1.2, 1.3, and 1.4); by 


far the most common version in use is 1.2, but this chapter also covers the Pbuffer func- 
tionality available in GLX 1.3. 


GLX provides several functions that manage visuals, contexts, and drawing surfaces. 
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X Window System Basics 

The X Window System provides a network-transparent interface for creating windows, 
drawing things on the screen, getting input from the user, and so forth. The program that 
manages one or more screens, keyboard, mouse, and other assorted input devices is 
usually called an X server. The connection to the server is managed by a Display pointer. 
You connect to the server using the XOpenDisplay() function and the display name: 


Display *display; 
display = XOpenDisplay(getenv("DISPLAY")) ; 


The default display name is, by convention, provided in the DISPLAY environment 
variable. When you have a display connection, you can create windows, draw graphics, 
and collect input from the user. 


Choosing a Visual 


Each window on the screen has a visual associated with it. Each visual has an associated 
class—DirectGray, DirectColor, PseudoColor, or TrueColor —that defines its properties. 
In general, most OpenGL rendering uses TrueColor visuals, which support arbitrary red, 
green, and blue color values. The other visual types map color numbers or indices to 
specific RGB values, making them useful only for specialized applications. 


The g1xChooseVisual() function determines the correct visual to use for a specific screen 
and combination of OpenGL features. The function accepts a Display pointer, screen 
number (usually 0), and attribute list. The attribute list is an array of integers. Each 
attribute consists of a token name (for example, GLX_RED_SIZE) and, for some attributes, a 
value. Table 15.1 lists the attribute list tokens that are defined. 


TABLE 15.1 GLX Visual Attribute List Constants 


Constant Description 

GLX_ACCUM_ALPHA_SIZE The number that follows specifies the minimum number of alpha bits that 
are required in the accumulation buffer. 

GLX_ACCUM_BLUE_SIZE The number that follows specifies the minimum number of blue bits that 
are required in the accumulation buffer. 

GLX_ACCUM_GREEN_SIZE The number that follows specifies the minimum number of green bits 
that are required in the accumulation buffer. 

GLX_ACCUM_RED_SIZE The number that follows specifies the minimum number of red bits that 
are required in the accumulation buffer. 

GLX_ALPHA_SIZE The number that follows specifies the minimum number of alpha bits that 
are required. 

GLX_AUX_BUFFERS The number that follows specifies the number of auxiliary buffers that are 


required. 


Constant 
GLX_BLUE_SIZE 


GLX_BUFFER_SIZE 


GLX_DEPTH_SIZE 


GLX_DOUBLEBUFFER 
GLX_GREEN_SIZE 


GLX_LEVEL 


GLX_RED_SIZE 


GLX_RGBA 
GLX_STENCIL_SIZE 


GLX_STEREO 


GLX_USE_GL 
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Description 

The number that follows specifies the minimum number of blue bits that 
are required. 

The number that follows specifies the number of color index bits that are 
desired. 

The number that follows specifies the minimum number of depth bits 
that are required. 

This token specifies that a double-buffered visual is desired. 

The number that follows specifies the minimum number of green bits 
that are required. 

This token specifies the buffer level in the number that follows; 0 is the 
main buffer, 1 is the first overlay buffer, -1 is the first underlay buffer, and 
so forth. 

The number that follows specifies the minimum number of red bits that 
are required. 

This token specifies that an RGBA visual is desired. 

The number that follows specifies the minimum number of stencil bits 
that are required. 

This token specifies that a stereo visual is desired; stereo visuals provide 
separate left and right eye images. 

This token specifies that OpenGL visuals are desired. This attribute is 


ignored because g1XChooseVisual() returns only OpenGL visuals. 


You might use the following code to find a double-buffered RGB visual: 


int attributes[] = { 
GLX_RGBA, 
GLX_DOUBLEBUFFER, 
GLX_RED_SIZE, 4, 
GLX_GREEN_SIZE, 4, 
GLX_BLUE_SIZE, 4, 
GLX_DEPTH_SIZE, 16, 
(1) 

}; 

Display *display; 

XVisualInfo *vinfo; 


vinfo = glxChooseVisual(display, DefaultScreen(display), attributes) ; 


An XVisualInfo pointer is returned; it provides information on the correct visual to use. If 
no matching visual can be found, a NULL pointer is returned, and you should retry with 
different attributes or inform the users that the window cannot be displayed on their 
system. 
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When you have found the correct visual to use, you can create an OpenGL context to use 
with a window or pixmap. 


Managing OpenGL Contexts 


OpenGL contexts are used to manage drawing in a single window or pixmap. Contexts are 
identified using the GLXContext data type. The g1XCreateContext() function creates a new 
context and accepts the Display pointer, an XVisualInfo pointer, a GLXContext to share 
with, and a boolean value indicating whether to create a direct or indirect context: 


GLXContext context; 
context = glXCreateContext(display, vinfo, ®, True); 


The display and visual information pointers are as initialized by the previous code exam- 
ples. The third argument specifies a GLXContext with which to share display lists, texture 
objects, and other stored data. You’ll likely specify this argument when creating multiple 
OpenGL windows for your application. If you have no other contexts defined, pass a value 
of 0 for the context. 


The fourth argument specifies whether a direct (True) or indirect (False) context is 
created. Direct contexts allow the OpenGL library to talk directly to the graphics hard- 
ware, providing the highest speed rendering. Indirect contexts send OpenGL drawing 
commands through the X server allowing for remote display over a network. Direct 
contexts cannot share with indirect contexts, and vice versa. This has the greatest impact 
on some types of offscreen rendering. Normally, you create a direct context. 


When you are finished with an OpenGL context, call the g1xXDestroyContext() function 
to free the resources it uses: 


glXDestroyContext(display, context); 


Creating an OpenGL Window 


When you have a Display pointer and GLXContext, you can use the XCreateWindow( ) 
function to create a window: 


Window window; 
XSetWindowAttributes winattrs; 


winattrs.event_mask = ExposureMask | VisibilityChangeMask } 
StructureNotifyMask | ButtonPressMask } 
ButtonReleaseMask | PointerMotionMask; 
Q; 


winattrs.border_pixel 
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winattrs.bit_gravity = StaticGravity; 
winmask CWBorderPixel | CWBitGravity | CWEventMask; 


window XCreateWindow(display, DefaultRootWindow(display) , 
@, 0, 400, 400, ®, vinfo->depth, InputOutput, 


vinfo->visual, winmask, &winattrs); 


After you create the window, you can show it using the XMapWindow() function and bind 
the OpenGL context to the window using the g1XMakeCurrent() function: 


XMapWindow(display, window) ; 
glXMakeCurrent(display, window, context); 


If you have multiple OpenGL windows, you need to call the g1XMakeCurrent() function 
before drawing in each window. Otherwise, you can call it once for the life of the 
program. 


Before you can actually draw in the window, you must wait for a MapNotify event, which 
tells your application that the X server has displayed your window on the screen. You can 
use the XNextEvent() function to wait for a MapNotify event or track whether you have 
seen the event in the normal event loop in your application. 


Double-Buffered Windows 


You create double-buffered windows by using a double-buffered visual. You get this type of 
visual by using the g1XChooseVisual() function with the GLX_DOUBLEBUFFER attribute. 


After the window has been created, the g1xSwapBuffers() function will swap the front 
and back buffer for the window: 


glxXSwapBuffers(display, window); 


The g1XSwapBuffers() function flushes any pending OpenGL drawing commands and 
may block until the next vertical retrace. 


Putting It All Together 

Figure 15.1 shows an OpenGL application written entirely using the Xlib and GLX func- 
tions covered in this section; this application displays a spinning cube. The user can click 
any mouse button to stop the rotation or drag the mouse to rotate the cube in any axis. 
The program responds to ConfigureNotify events to track when the window is resized 
and MapNotify and UnmapNotify events when the window is shown or iconified. Listing 
15.3 shows the source for this application. 
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FIGURE 15.1 The Xlib spinning cube example. 


LISTING 15.3 The xlib.c Sample Program 
/* 

* Include necessary headers... 

=/ 


#include <stdio.h> 
#include <stdlib.h> 
#include <X11/Xlib.h> 
#include <X11/Xatom.h> 
#include <GL/glx.h> 
#include <GL/gl.h> 


#include <sys/select.h> 
#include <sys/types.h> 
#include <sys/time.h> 


/* 
* Globals... 
bf 
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LISTING 15.3 Continued 


float 


int 


int 


/* 
* Functions... 
oH 


void 
void 
void 
void 
void 


/* 
* 'main()' - Ma 
fi 


int 
main(int argc, 
char *argv[ 


Bool 
GLXContext 
Display 
Window 
XVisualInfo 
XSetWindowAttr 
int 

XEvent 
XWindowAttribu 
struct timeval 
fd_set 

int 

static int 


CubeRotation[3], /* Rotation of cube */ 
CubeRate[3]; /* Rotation rate of cube */ 
CubeMouseButton, /* Button that was pressed */ 
CubeMousex, /* Start X position of mouse */ 
CubeMouseY; /* Start Y position of mouse */ 
CubeWidth, /* Width of window */ 
CubeHeight; /* Height of window */ 
DisplayFunc(void) ; 

IdleFunc(void) ; 


MotionFunc(int x, int y); 
MouseFunc(int button, int state, int x, int y); 
ReshapeFunc(int width, int height); 


in entry for example program. 


/* O - Exit status */ 
/* I - Number of command-line args */ 


]) /* I - Command-line args */ 
mapped; /* Is the window mapped? */ 
context; /* OpenGL context */ 
*display; /* X display connection */ 
window; /* X window */ 
*vinfo; /* X visual information */ 

ibutes winattrs; /* Window attributes */ 
winmask; /* Mask for attributes */ 
event; /* Event data */ 

tes windata; /* Window data */ 
timeout; /* Timeout interval for select() */ 
input; /* Input set for select() */ 
ready; /* Event ready? */ 


attributes[] = /* OpenGL attributes */ 
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LISTING 15.3 Continued 


{ 
GLX_RGBA, 
GLX_DOUBLEBUFFER, 
GLX_RED_SIZE, 8, 
GLX_GREEN_SIZE, 8, 
GLX_BLUE_SIZE, 8, 
GLX_DEPTH_ SIZE, 16, 


t) 
}; 
/* 
* Open a connection to the X server... 
ml 


display = XOpenDisplay(getenv("DISPLAY") ); 


/* 
* Find the proper visual for an OpenGL window... 
sy | 


vinfo = glXChooseVisual(display, DefaultScreen(display), attributes) ; 
/* 


* Create the window... 
a 


winattrs.event_mask ExposureMask | VisibilityChangeMask } 
StructureNotifyMask | ButtonPressMask | 
ButtonReleaseMask | PointerMotionMask; 
winattrs.border_pixel = Q; 

winattrs.bit_gravity = StaticGravity; 


winmask CWBorderPixel | CWBitGravity | CWEventMask; 


i 


window = XCreateWindow(display, DefaultRootWindow(display) , 
@, 0, 400, 400, ®, vinfo->depth, InputOutput, 
vinfo->visual, winmask, &winattrs) ; 


XChangeProperty(display, window, XA_WM_NAME, XA_STRING, 8, 0, 
(unsigned char *)argv[®@], strlen(argv[Q])); 
XChangeProperty(display, window, XA_WM_ICON_NAME, XA_STRING, 8, 0, 
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LISTING 15.3 Continued 
(unsigned char *)argv[@], strlen(argv[®])); 
XMapWindow(display, window) ; 
{* 
* Create the OpenGL context... 


dl 


context = glXCreateContext(display, vinfo, ®, True); 
glXMakeCurrent(display, window, context); 


/* 

* Setup remaining globals... 
st | 

CubeWidth = 400; 
CubeHeight = 400; 


CubeRotation[®] = 45.0f; 
CubeRotation[1] = 45.0f; 
CubeRotation[2] = 45.0f; 


CubeRate[Q] = 1.0f; 
CubeRate[1] = 1.0f; 
CubeRate[2] = 1.0f; 
/* 

* Loop forever... 

di | 


mapped = False; 


for (53) 

{ 
/* 
* Use select() to respond asynchronously to events; when the window is 
* not mapped, we wait indefinitely; otherwise we'll timeout after 20ms 
* to rotate the cube... 
By 


if (mapped) 
{ 
FD_ZERO(&£input) ; 
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LISTING 15.3 Continued 
FD_SET(ConnectionNumber (display), &input) ; 


timeout.tv_sec 
timeout. tv_usec 


Q; 
20000; 


ready = select(ConnectionNumber(display) + 1, &input, NULL, NULL, 


&timeout) ; 
} 
else 
ready = 1; 
if (ready) 
{ 
/* 
* An event is ready, handle it... 
*/ 


XNextEvent(display, &event); 


switch (event.type) 
{ 
case MapNotify : 
mapped = True; 


case ConfigureNotify : 
XGetWindowAttributes(display, window, &windata) ; 


ReshapeFunc(windata.width, windata.height) ; 
break; 


case UnmapNotify : 
mapped = False; 
break; 


case ButtonPress : 
MouseFunc(event.xbutton.button, @, event.xbutton.x, 
event.xbutton.y) ; 
break; 


case ButtonRelease : 
MouseFunc(event.xbutton.button, 1, event.xbutton.x, 
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LISTING 15.3 Continued 


event.xbutton.y); 


break; 


case MotionNotify : 
if (event.xmotion.state & (ButtoniMask | Button2Mask | Button3Mask) ) 
MotionFunc(event.xmotion.x, event.xmotion.y) ; 


break; 
} 
} 
/* 
* Redraw if the window is mapped... 
a 


if (mapped) 

{ 
/* 
* Update the cube rotation... 
st 


IdleFunc(); 


/* 
* Draw the cube... 
*i) 


DisplayFunc(); 


/* 
* Swap the front and back buffers... 
*/ 


glXSwapBuffers(display, window) ; 


} 
} 


/* 
* 'DisplayFunc()' - Draw a cube. 
“i 
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LISTING 15.3 Continued 


void 
DisplayFunc(void) 
{ 
int 2 ees fe /* Looping vars */ 
static const GLfloat corners[8][3] = /* Corner vertices */ 
{ 
£ OF, VWOF;. 1.0F }, /* Front top right */ 
{ 1.0f, -1.0f, 1.0f }, /* Front bottom right */ 
dt =A OF,, =1508S. 1.0F 3}; /* Front bottom left */ 
{. =1OF;. 020t;,. 1<0F F, /* Front top left */ 
f° 420f) ~1c0Ty, -- 126 }, /* Back top right */ 
{ 1.0f, -1.0f, -1.0f }, /* Back bottom right */ 
{ -=1..0F,..=1cOF,.--1,.0F }; /* Back bottom left */ 
{ -1.0f, 1.0f, -1.0f } /* Back top left */ 
}; 
static const int sides[6][4] = /* Sides */ 
{ 
£05 1925.3" }, {* Front: */ 
{A 55-6. 7b; /* Back */ 
{ 0, 1, 5, 4}, /* Right */ 
tity andy. 6 ps /* Lett */ 
£0. 3S) 7547}. /* Top’ */ 
{i152 5 6 Be} /* Bottom */ 
}5 
static const GLfloat colors[6][3] = /* Colors */ 
{ 
{ 1.0f, 0.0f, 0.Of }, /* Red */ 
{ 0.0f, 1.0f, 0.0f }, /* Green */ 
{ 1.0f, 1.0f, 0.0f }, /* Yellow */ 
{ 0.0f, 0.0f, 1.0f }, /* Blue */ 
{ 1.0f, 0.0f, 1.0f }, /* Magenta */ 
{ 0.0f, 1.0f, 1.0f } /* Cyan */ 
}5 
/* 
* Clear the window... 
id | 


glViewport(®, @, CubeWidth, CubeHeight) ; 
glClearColor(0.0f, 0.0f, 0.0f, 0.0f); 
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LISTING 15.3 Continued 


glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


/* 
* Setup the matrices... 
ef 


glMatrixMode(GL_PROJECTION) ; 

glLoadidentity(); 

glOrtho(-2.0f, 2.0f, 
-2.0f * CubeHeight / CubeWidth, 2.0f * CubeHeight / CubeWidth, 
-2.0f, 2.0f); 


glMatrixMode(GL_MODELVIEW) ; 

glLoadIdentity(); 

glRotatef (CubeRotation[®], 1.0f, 0.0f, 0.0f); 
glRotatef (CubeRotation[1], 0.0f, 1.0f, 0.0f); 
glRotatef(CubeRotation[2], 0.0f, 0.0f, 1.0f); 


/* 
* Draw the cube... 
st 


glEnable(GL_DEPTH_TEST) ; 
glBegin(GL_QUADS) ; 


fora(ic= 05. 4.5 6s 1. +4) 
4 
glColor3fv(colors[i]); 
FOR 05 ja< 45: j-th) 
glVertex3fv(corners[sides[i][j]]); 


glEnd() ; 
} 


/* 
* ‘IdleFunc()' - Rotate and redraw the cube. 
“} 
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LISTING 15.3 Continued 


void 

IdleFunc(void) 

{ 
CubeRotation[®] += CubeRate[0]; 
CubeRotation[1] += CubeRate[1]; 
CubeRotation[2] += CubeRate[2]; 

} 


/* 
* 'MotionFunc()' - Handle mouse pointer motion. 
xi 


void 
MotionFunc(int x, /* I - X position */ 
int y) /* I - Y position */ 
{ 
/* 
* Get the mouse movement... 
Ef 


CubeMousex; 
CubeMouseY; 


/* 

* Update the cube rotation rate based upon the mouse movement and 
* button... 

| 


switch (CubeMouseButton) 
{ 
case Q : /* Button 1 */ 
CubeRate[@] = 0.01f * y; 
CubeRate[1] = @.01f * x; 
CubeRate[2] = 0.0f; 
break; 


case 1: /* Button 2 */ 
CubeRate[@] = 0.0f; 
CubeRate[1] = 0.01f * y; 
CubeRate[2] = 0.01f * x; 


LISTING 15.3 Continued 


break; 


default : 
CubeRate[0] 
CubeRate[1] 
CubeRate[2] 
break; 


Q.01f * y; 
Q.0f; 
Q.01f * x; 


/* 
* 'MouseFunc() ' 
1 / 


void 
MouseFunc(int button, 
int state, 
int x, 
int y) 
{ 
/* 
* Only respond to button presses... 
=) 


if (state) 
return; 


{* 
* Save the mouse state... 
ef 


CubeMouseButton = button; 
CubeMouseX = X; 
CubeMouseY 


i) 
bend 


/* 
* Zero-out the rotation rates... 
sf 


CubeRate[@] = 0.Of; 
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/* Button 3 */ 


/* 
/* 
/* 
/* 


- Handle mouse button press/release events. 


I - Button that was pressed */ 
I - Button state (1 = down) */ 
I - X position */ 
I - Y position */ 
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LISTING 15.3 Continued 


CubeRate[1] = 0.0f; 
CubeRate[2] = 0.0f; 
} 
/* 
* 'ReshapeFunc()' - Resize the window. 
i 
void 
ReshapeFunc(int width, /* I - Width of window */ 
int height) /* I - Height of window */ 
{ 
CubeWidth = width; 
CubeHeight = height; 
} 


Creating Bitmap Fonts for OpenGL 


The GLX extension provides a single function called g1xUsexFont() for converting an X 
font to OpenGL bitmaps. Each bitmap is placed in a display list, allowing you to display a 
string of text using the glCallLists() function. You start by looking up an X font using 
the XLoadQueryFont() function: 


XFontStruct *font; 
font = XLoadQueryFont(display, "-*-courier-bold-r-normal--14-*-*-*-*-*-*-*"); 


The sample code loads a 14-pixel Courier Bold font; however, any X font can be used. 
After you load the X font, you call glGenLists() to create display lists for the number of 
characters you want to use and g1XUseXFont() to load the display list bitmaps. In the 
following sample code, characters from the space (32) to delete (127) are loaded into 96 
display lists: 


GLuint listbase; 


listbase = glGenLists(96) ; 
glXUseXFont(font->fid, ' ', 96, listbase); 


Then you can draw text using a combination of the glRasterPos(), glPushAttrib(), 
glListBase(), glCallLists(), and glPopAttrib() functions, as follows: 


char *s = "Hello, World!"; 


glPushAttrib(GL_LIST_BIT) ; 
glListBase(CubeFont - ' '); 


glRasterPos3f(0.0f, 0.0f, 0.0f); 
glCallLists(strlen(s), GL_BYTE, s); 
glPopAttrib(); 


Creating Bitmap Fonts for OpenGL 


The example in Listing 15.4 uses this code to draw the names of each side of the cube. 


Figure 15.2 shows the result. 


[¥ pulipfonts 


FIGURE 15.2 The Xlib spinning cube with text example. 


LISTING 15.4 The xlibfonts.c Sample Program 
/* 

* Include necessary headers... 

“if 


#include <stdio.h> 
#include <stdlib.h> 
#include <X11/Xlib.h> 
#include <X11/Xatom.h> 
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LISTING 15.4 Continued 


#include 
#include 


#include 
#include 
#include 


<GL/g1lx.h> 
<GL/gl.h> 


<sys/select.h> 
<sys/types.h> 
<sys/time.h> 


/* Rotation of cube */ 

/* Rotation rate of cube */ 

/* Button that was pressed */ 

/* Start X position of mouse */ 

/* Start Y position of mouse */ 

/* Width of window */ 

/* Height of window */ 

/* Display list base for font */ 


MouseFunc(int button, int state, int x, int y); 


/* O - Exit status */ 


/* 
* Globals... 
my] 
float CubeRotation[3], 
CubeRate[3]; 
int CubeMouseButton, 
CubeMousex, 
CubeMouseY ; 
int CubeWidth, 
CubeHeight; 
GLuint CubeFont; 
/* 
* Functions... 
*/ 
void DisplayFunc (void) ; 
void IdleFunc(void) ; 
void MotionFunc(int x, int y); 
void 
void ReshapeFunc(int width, int height); 
/* 
* 'main()' - Main entry for example program. 
*/ 
int 
main(int argc, 


char *argv[]) 


/* I - Number of command-line args */ 
/* I - Command-line args */ 


LISTING 15.4 Continued 


Creating Bitmap Fonts for OpenGL 


Is the window mapped? */ 
OpenGL context */ 

X display connection */ 

X window */ 

X visual information */ 

X font information */ 
Window attributes */ 

Mask for attributes */ 
Event data */ 

Window data */ 

Timeout interval for select() */ 
Input set for select() */ 
Event ready? */ 

OpenGL attributes */ 


Bool mapped; {= 
GLXContext context; [* 
Display *display; [* 
Window window; /* 
XVisualInfo *vinfo; hl 
XFontStruct *font; /* 
XSetWindowAttributes winattrs; {* 
int winmask; (* 
XEvent event; /* 
XWindowAttributes windata; {® 
struct timeval timeout; [Xs 
fd_set input; has 
int ready; 12 
static int attributes[] = /* 
{ 
GLX_RGBA, 
GLX_DOUBLEBUFFER, 
GLX_RED_SIZE, 8, 
GLX_GREEN_SIZE, 8, 
GLX_BLUE_SIZE, 8, 
GLX_DEPTH_SIZE, 16, 
1) 
}5 
/* 


* Open a connection to the X server... 


oY 


display = XOpenDisplay(getenv("DISPLAY") ) ; 


/* 


* Find the proper visual for an OpenGL window... 


in} | 


vinfo = glXChooseVisual(display, DefaultScreen(display), attributes) ; 


/* 
* Create the window... 
a 
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LISTING 15.4 Continued 


winattrs.event_mask = ExposureMask | VisibilityChangeMask | 
StructureNotifyMask | ButtonPressMask | 
ButtonReleaseMask | PointerMotionMask; 

winattrs.border_pixel = 0; 

winattrs.bit_gravity = StaticGravity; 

winmask CWBorderPixel | CWBitGravity | CWEventMask; 


window = XCreateWindow(display, DefaultRootWindow(display) , 
@, @, 400, 400, 0, vinfo->depth, InputOutput, 
vinfo->visual, winmask, &winattrs) ; 


XChangeProperty(display, window, XA_WM_NAME, XA_STRING, 8, Q, 
(unsigned char *)argv[®], strlen(argv[®])); 

XChangeProperty(display, window, XA_WM_ICON_NAME, XA_STRING, 8, Q, 
(unsigned char *)argv[@], strlen(argv[@])); 


XMapWindow(display, window) ; 
/* 
* Create the OpenGL context... 


*y 


context = glxXCreateContext(display, vinfo, 0, True); 
glXMakeCurrent(display, window, context); 


/* 

* Setup remaining globals... 
*/ 

CubeWidth = 400; 
CubeHeight = 400; 
CubeRotation[@] = 45.0f; 
CubeRotation[1] = 45.0f; 
CubeRotation[2] = 45.0f; 
CubeRate[Q] = 1.0f; 
CubeRate[1] = 1.0f; 
CubeRate[2] = 1.0f; 
/* 


* Setup font... 
*} 
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LISTING 15.4 Continued 
font 


XLoadQueryFont (display, 
".*-courier-bold-r-normal--14-*-*-*-*-*-*-*"); 
CubeFont = glGenLists(96) ; 


glXUseXFont(font->fid, ' ', 96, CubeFont) ; 


/* 
* Loop forever... 
i [ 


mapped = False; 


for (53) 

{ 
/* 
* Use select() to respond asynchronously to events; when the window is 
* not mapped, we wait indefinitely; otherwise we'll timeout after 20ms 
* to rotate the cube... 
LY 


if (mapped) 

{ 
FD_ZERO(&input) ; 
FD_SET(ConnectionNumber(display), &input) ; 


timeout.tv_sec 
timeout. tv_usec 


0; 
20000; 


ready = select(ConnectionNumber(display) + 1, &input, NULL, NULL, 
&timeout) ; 
} 
else 
ready = 1; 
if (ready) 
{ 
/* 
* An event is ready, handle it... 
ta | 


XNextEvent(display, &event) ; 
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LISTING 15.4 Continued 


switch (event.type) 
{ 
case MapNotify : 
mapped = True; 


case ConfigureNotify : 
XGetWindowAttributes(display, window, &windata) ; 


ReshapeFunc(windata.width, windata.height) ; 
break; 


case UnmapNotify : 
mapped = False; 
break; 


case ButtonPress : 
MouseFunc(event.xbutton.button, @, event.xbutton.x, 
event.xbutton.y) ; 
break; 


case ButtonRelease : 
MouseFunc(event.xbutton.button, 1, event.xbutton.x, 
event.xbutton.y) ; 
break; 


case MotionNotify : 
if (event.xmotion.state & (ButtoniMask | Button2Mask | Button3Mask) ) 
MotionFunc(event.xmotion.x, event.xmotion.y); 


break; 
} 
} 
/* 
* Redraw if the window is mapped... 
oH 


if (mapped) 

{ 
/* 
* Update the cube rotation... 
tf 


LISTING 15.4 Continued 
IdleFunc(); 


/* 
* Draw the cube... 
nf 


DisplayFunc(); 
/* 
* Swap the front and back buffers... 


| 


glXSwapBuffers(display, window) ; 


Creating Bitmap Fonts for OpenGL 


} 
} 
} 
/* 
* 'DisplayFunc()' - Draw a cube. 
Sif 
void 
DisplayFunc(void) 
{ 
int Lee His /* Looping vars */ 
static const GLfloat corners[8][3] = /* Corner vertices 
{ 
{ VO; a20f, Ot }, i* 
{. (OTS. =f, 1.0 4; Hie 
{31.0f;, ~1.0h, net 3; pe 
{io =sOfjs 1.0f, 5. 160i}, /* 
{ AOR: Ot, 1G, pe 
{ “Of; —=1. 08. S1at +; His 
{ -1.0f, -1.0f, -1.0f }, Md 
{ =1.0f). 1.08, -1-0f-} Meg 
}5 
static const int sides[6][4] = /* Sides */ 
{ 
{ 0, 1, 2, 3 }, Hes 
{ 4, , 6, t¥5 thd 


| 


Front top right */ 
Front bottom right */ 
Front bottom left */ 
Front top left */ 
Back top right */ 
Back bottom right */ 
Back bottom left */ 
Back top left */ 


Front */ 
Back */ 
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LISTING 15.4 Continued 


PO. 45,4) /* Right */ 
{ 2, 3, 7; 6 }; {* Left */ 
{ 0, 3, 7, 4}, [* Top */ 
1 Ay 125). 65-5: /* Bottom */ 
}; 
static const GLfloat colors[6][3] = /* Colors */ 
{ 
{ 1.0f, 0.0f, 0.0f }, /* Red */ 
{ 0.0f, 1.0f, 0.0f }, /* Green */ 
{ 1.0f, 1.0f, 0.0f }, /* Yellow */ 
{ 0.0f, 0.0f, 1.0f }, /* Blue */ 
{ 1.0f, 0.0f, 1.0f }, /* Magenta */ 
{ @.0f, 1.0F,;. 1.0F } /* Cyan */ 
}5 
/* 
* Clear the window... 
i | 


glViewport(®, ®, CubeWidth, CubeHeight) ; 
glClearColor(0.0f, 0.0f, @.0f, 0.0f); 
glClear(GL_COLOR_BUFFER_BIT } GL_DEPTH_BUFFER_BIT); 


/* 
* Setup the matrices... 
at | 


glMatrixMode(GL_PROJECTION) ; 

glLoadidentity(); 

glOrtho(-2.0f, 2.0f, 
-2.0f * CubeHeight / CubeWidth, 2.@f * CubeHeight / CubeWidth, 
-2.0f, 2.0f); 


glMatrixMode(GL_MODELVIEW) ; 

glLoadiIdentity(); 

glRotatef(CubeRotation[®], 1.0f, 0.0f, 0.0f); 
glRotatef (CubeRotation[1], 0.0f, 1.0f, @.Of); 
glRotatef (CubeRotation[2], 0.0f, @.0f, 1.0f); 


/* 


LISTING 15.4 Continued 


* Draw the cube... 
| 


glEnable(GL_DEPTH_TEST) ; 
g1Begin(GL_QUADS) ; 


for. (d: =(O2" 4d -s.63 2 +) 
{ 
glColor3fv(colors[i]); 
Tor. = Op. <45 Jt) 
glVertex3fv(corners[sides[i][j]]); 


glEnd(); 


/* 
* Draw lines coming out of the cube... 
bai 


glColor3f(1.0f, 1.0f, 1.0f); 


glBegin(GL_LINES) ; 
glVertex3f(@.0f, 0.0f, -1.5f); 
glVertex3f(@.0f, 0.0f, 1.5f); 


glVertex3f(-1.5f, @.0f, 0.0f); 
glVertex3f(1.5f, @.0f, 0.0f); 


glVertex3f(0.0f, 1.5f, 0.0f); 
glVertex3f(@.0f, -1.5f, 0.0f); 
glEnd(); 


/* 
* Draw text for each side... 
cdf 


glPushAttrib(GL_LIST_BIT) ; 
glListBase(CubeFont - ' '); 


Creating Bitmap Fonts for OpenGL 
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LISTING 15.4 Continued 


glRasterPos3f(0.0f, @.0f, -1.5f); 
glCallLists(4, GL_BYTE, "Back"); 


glRasterPos3f(0.0f, 0.0f, 1.5f); 
glCallLists(5, GL_BYTE, "Front"); 


glRasterPos3f(-1.5f, @.0f, 0.0f); 
glCallLists(4, GL_BYTE, "Left"); 


glRasterPos3f(1.5f, 0.0f, @.0f); 
glCallLists(5, GL_BYTE, "Right"); 


glRasterPos3f(@.0f, 1.5f, @.Of); 
glCallLists(3, GL_BYTE, "Top"); 


glRasterPos3f(0.0f, -1.5f, 0.0f); 
glCallLists(6, GL_BYTE, "Bottom"); 
glPopAttrib(); 
} 


/* 
* 'IdleFunc()' - Rotate and redraw the cube. 
a 


void 

IdleFunc(void) 

{ 
CubeRotation[0] += CubeRate[Q]; 
CubeRotation[1] += CubeRate[1]; 


CubeRotation[2] += CubeRate[2]; 
iy 
/* 
* ‘MotionFunc()' - Handle mouse pointer motion. 
=i 
void 
MotionFunc(int x, /* I - X position */ 


int y) {* I = ¥ position */ 


LISTING 15.4 Continued 


Creating Bitmap Fonts for OpenGL 


* Update the cube rotation rate based upon the mouse movement and 


{ 
/* 
* Get the mouse movement... 
st 
= CubeMousex; 
= CubeMouseY; 
/* 
* button... 
sf 


switch (CubeMouseButton) 


{ 
case 0: 
CubeRate[ 0] 
CubeRate[1] 
CubeRate[2] 
break; 


case 1: 
CubeRate[0] 
CubeRate[1] 
CubeRate[2] 
break; 


default : 
CubeRate[0] 
CubeRate[1] 
CubeRate[2] 
break; 


/* 
* 'MouseFunc() ' 
| 


void 


Ss 


Ss 


.O1f 
.O1f 
OF; 


OF; 
.O1F 
.O1F 


.O1f 
OF; 
.O1f 


y; 


y; 


ys 


xX; 


/* Button 1 */ 


/* Button 2 */ 


/* Button 3 */ 


- Handle mouse button press/release events. 
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LISTING 15.4 Continued 


MouseFunc(int button, f* 
int state, ye 
int x, /* 
int y) {* 


- Button that was pressed */ 
- Button state (1 = down) */ 
- X position */ 
Y position */ 


s == = 


{ 

/* 
* Only respond to button presses... 
*/ 


if (state) 
return; 


{* 
* Save the mouse state... 
*/ 


CubeMouseButton = button; 
CubeMousexX =X; 
CubeMouseY y; 


{* 
* Zero-out the rotation rates... 
i] 


CubeRate[Q] 

CubeRate[1] 

CubeRate[2] 
} 


Q.0f; 
0.0f; 
Q.0f; 


/* 
* 'ReshapeFunc()' - Resize the window. 
Lit 


void 
ReshapeFunc(int width, /* I - Width of window */ 
int height) /* I - Height of window */ 
{ 
CubeWidth = width; 
CubeHeight = height; 
} 


Offscreen Rendering 


Offscreen Rendering 


GLX supports two types of offscreen rendering, each with its own advantage: GLX 
pixmaps and Pbuffers. 


Using GLX Pixmaps 

GLX pixmaps are the original type of offscreen rendering and generally support TrueColor 
and PseudoColor visuals. They are generally used when portability is desired over perfor- 
mance; although GLX pixmaps are available on all platforms, GLX pixmaps are not hard- 
ware accelerated. GLX pixmaps also often support larger bit depths and dimensions than 
the graphics hardware, making them ideal for offline rendering of images when graphics 
card memory is limited. 


As with OpenGL windows, GLX pixmaps start with a call to the g1xChooseVisual() func- 
tion to find an appropriate visual. Because some systems and graphics cards provide only 
double-buffered OpenGL visuals, you have to check for both single- and double-buffered 
visuals: 


Display *display; 
XVisualInfo *vinfo; 
static int attributes[] = 
{ 
GLX_RGBA, 
GLX_RED_SIZE, 8, 
GLX_GREEN_SIZE, 8, 
GLX_BLUE_SIZE, 8, 
GLX_DEPTH_SIZE, 16, 
Q, /* Save space for GLX_DOUBLEBUFFER */ 
Q 
hs 


display = XOpenDisplay(getenv("DISPLAY")); 
vinfo = glXChooseVisual(display, DefaultScreen(display), attributes) ; 
if (!vinfo) 


{ 
{* 
* If no single-buffered visual is available, try a double-buffered one... 
bet / 
attributes[9] = GLX_DOUBLEBUFFER; 
vinfo = glXChooseVisual(display, DefaultScreen(display) , 


attributes) ; 
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When you have an appropriate visual, you can create an X Pixmap using the 
XCreatePixmap() function; this pixmap will hold the actual pixels for your offscreen 
buffer. It is then bound to GLX for OpenGL rendering using the g1XCreateGLXPixmap() 
function: 


Pixmap pixmap; 
GLXPixmap glxpixmap; 


pixmap = XCreatePixmap(display, DefaultRootWindow(display) , 
1024, 1024, vinfo->depth); 
glxpixmap = glXCreateGLXPixmap(display, vinfo, pixmap) ; 


Finally, you call the g1xCreateContext() function to create a context for the GLX pixmap, 
specifying a value of False for the fourth parameter for an indirect rendering context: 


GLXContext context; 


context = glxXCreateContext(display, vinfo, ®, False); 
glXMakeCurrent(display, glxpixmap, context) ; 


You can then draw into the pixmap using OpenGL functions and read the results back 
using the glReadPixels() function. Listing 15.5 shows a variation of the previous sample 
program that creates a GLX pixmap, draws a cube, reads the image using glReadPixels(), 
and writes the result to a PPM image file called g1xpixmap.ppm. 


LISTING 15.5 GLX Pixmap Sample Program 
/* 

* Include necessary headers... 

*y 


#include <stdio.h> 
#include <stdlib.h> 
#include <X11/Xlib.h> 
#include <X11/Xatom.h> 
#include <GL/glx.h> 
#include <GL/gl.h> 


/* 
* Globals... 
a 


float CubeRotation[3], /* Rotation of cube */ 
CubeRate[3]; /* Rotation rate of cube */ 


LISTING 15.5 Continued 


int CubeWidth, [* 
CubeHeight; /* 


Offscreen Rendering 


Width of window */ 
Height of window */ 


O - Exit status */ 
I - Number of command-line args */ 
I - Command-line args */ 


OpenGL context */ 

X display connection */ 

X pixmap */ 

GLX pixmap */ 

X visual information */ 
PPM file pointer */ 
Current row */ 

One line of RGB pixels */ 
OpenGL attributes */ 


Save space for GLX_DOUBLEBUFFER */ 


/* 
* Functions... 
Ef 
void DisplayFunc(void) ; 
is 
* ‘'main()' - Main entry for example program. 
eit 
int [* 
main(int argc, (* 
char *argv[]) he 
{ 
GLXContext context; es 
Display *display; [* 
Pixmap pixmap; fie! 
GLXPixmap glxpixmap; Hf? 
XVisualInfo *vinfo; (= 
FILE *fp; /* 
int y; [* 
unsigned char pixels[3072]; Ups: 
static int attributes[] = /* 
{ 
GLX_RGBA, 
GLX_RED_SIZE, 8, 
GLX_GREEN SIZE, 8, 
GLX_BLUE_SIZE, 8, 
GLX_DEPTH_SIZE, 16, 
Q, [ 
ti) 
}5 
/* 


* Open a connection to the X server... 
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LISTING 15.5 Continued 


ih 

display = XOpenDisplay(getenv("DISPLAY") ) ; 
/* 

* Find the proper visual for a GLX pixmap... 


i 


vinfo = glXChooseVisual(display, DefaultScreen(display), attributes) ; 
if (!vinfo) 


{ 
/* 
* If no single-buffered visual is available, try a double-buffered one... 
*/ 
attributes[9] = GLX_DOUBLEBUFFER; 
vinfo = glXChooseVisual(display, DefaultScreen(display) , 
attributes) ; 
} 
if (!vinfo) 
{ 
puts("No OpenGL visual available!"); 
return (1); 
} 
/* 
* Create the pixmap... 
sd | 
pixmap = XCreatePixmap(display, DefaultRootWindow(display) , 


1024, 1024, vinfo->depth) ; 
glxpixmap = glXCreateGLXPixmap(display, vinfo, pixmap) ; 


/* 
* Create the OpenGL context... 
wy 


context = glXCreateContext(display, vinfo, ®, False); 
glXMakeCurrent(display, glxpixmap, context); 


LISTING 15.5 Continued 


/* 

* Setup remaining globals... 
yi) 

CubeWidth = 1024; 
CubeHeight = 1024; 


CubeRotation[0] = 45.0f; 
CubeRotation[1] = 45.0f; 
CubeRotation[2] = 45.0f; 
CubeRate[0] = 1.0f; 
CubeRate[1] = 1.0f; 
CubeRate[2] = 1.0f; 


/* 
* Draw a Cube... 
7 | 


DisplayFunc(); 


/* 
* Read back the RGB pixels and write the result as a PPM file. 
*/ 


if ((fp = fopen("glxpixmap.ppm", "wb")) == NULL) 
perror("Unable to create glxpixmap.ppm") ; 
else 
{ 
/* 
* Write a PPM image from top to bottom... 
si | 


fputs("P6\n1024 1024 255\n", fp); 


for (y = 1023; y >= 0; y --) 

{ 
glReadPixels(®@, y, 1024, 1, GL_RGB, GL_UNSIGNED_BYTE, pixels); 
fwrite(pixels, 1024, 3, fp); 

} 


fclose(fp); 


Offscreen Rendering 
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LISTING 15.5 Continued 
/* 


* Destroy all resources we used and close the display... 


sey | 


glXDestroyContext(display, context) 


glXDestroyGLXPixmap(display, glxpixmap) ; 


XFreePixmap(display, pixmap) ; 
XCloseDisplay (display) ; 


return (0); 


{* 
* 'DisplayFunc()' - Draw a cube. 
sa | 


void 
DisplayFunc(void) 
{ 


int i, j; 


{ 

Of, 
Of, - 
Of, - 
Of, 
Of, 
Of, - 
Of, - 
-1.0f, 


Ce ee tee ee oe oe ee 
. . ‘ 

a ee ee ee oe ce a 

ee ee ee ee ee ee 9 


}; 


static const int sides[6][4] = 


. 
d 


lot; 1:.0T }, 
Of, 1.0Ff }, 
1Of,.  AOF }; 
2OF,. 1.0f }, 
Of, -1.0F }, 
Of, -1.0F }, 
Of, -1.0f }, 
Of, -1.0F } 
/* Sides */ 

}; 

}; 

}; 

}s 

}, 

} 


aro N © 


/* Looping vars */ 
static const GLfloat corners[8][3] = /* Corner vertices 


/* 
{* 
[* 
/* 
/* 
/* 
/* 
/* 


/* 
/* 
{* 
/* 
/* 
/* 


a 


Front top right */ 
Front bottom right */ 
Front bottom left */ 
Front top left */ 
Back top right */ 
Back bottom right */ 
Back bottom left */ 
Back top left */ 


Front */ 
Back */ 
Right */ 
Left */ 
Top */ 
Bottom */ 
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LISTING 15.5 Continued 


static const GLfloat colors[6][3] = /* Colors */ 


{ 
{ 1.0f, 0.0f, 0.O0f }, /* Red */ 
{ 0.0f, 1.0f, 0.Of }, /* Green */ 
{ 1.0f, 1.0f, 0.0f }, /* Yellow */ 
{ 0.0f, 0.0f, 1.0f }, /* Blue */ 
{ 1.0f, 0.0f, 1.0f }, /* Magenta */ 
{ 0.0f, 1.0f, 1.0f } /* Cyan */ 
}3 
/* 
* Clear the window... 
*/ 


glViewport(®, ®, CubeWidth, CubeHeight) ; 
glClearColor(0.0f, 0.0f, 0.0f, 0.0f); 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


{= 
* Setup the matrices... 
i 


glMatrixMode (GL_PROJECTION) ; 

glLoadIdentity(); 

glOrtho(-2.0f, 2.0f, 
-2.0f * CubeHeight / CubeWidth, 2.0f * CubeHeight / CubeWidth, 
-2.0f, 2.0f); 


glMatrixMode (GL_MODELVIEW) ; 

glLoadIdentity(); 

glRotatef(CubeRotation[®], 1.0f, 0.0f, 0.0f); 
glRotatef(CubeRotation[1], 0.0f, 1.0f, 0.0f); 
glRotatef (CubeRotation[2], 0.0f, 0.0f, 1.0f); 


[* 
* Draw the cube... 


*/ 


glEnable(GL_DEPTH_TEST) ; 
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LISTING 15.5 Continued 
glBegin(GL_QUADS) ; 


for (1 = O3-1°< 65) et) 
{ 
glColor3fv(colors[i]); 
for (j = 03 ji < 4gnge +4) 
glVertex3fv(corners[sides[i][j]]); 


glEnd(); 


Using Pbuffers 


Pbuffers, the second type of offscreen buffer, are supported by GLX 1.3 implementations. 
Pbuffers use graphics memory instead of X pixmaps and are hardware accelerated, provid- 
ing faster offscreen rendering. However, the use of graphics memory often limits the 
maximum size of a Pbuffer, and Pbuffers are not universally supported. 


Using Pbuffers, unlike OpenGL windows and GLX pixmaps, you start by choosing a frame- 
buffer configuration using the glXChooseFBConfig() function instead of 
glXChooseVisual(): 


Display *display; 
int nconfigs; 
GLXFBConfig *configs; 
static int attributes[] = 
{ 
GLX_RGBA, 
GLX_RED_SIZE, 8, 
GLX_GREEN_SIZE, 8, 
GLX_BLUE_SIZE, 8, 
GLX_DEPTH_SIZE, 16, 


Q, /* Save space for GLX_DOUBLEBUFFER */ 
t) 

}5 

display = XOpenDisplay(getenv(“DISPLAY")); 


configs = glXChooseFBConfig(display, DefaultScreen(display), attributes, 
&nconfigs) ; 
if (!configs) 


{ 


Offscreen Rendering 


attributes[3] 
configs 


GLX_DOUBLEBUFFER; 
glXChooseFBConfig(display, DefaultScreen(display), 
attributes, &nconfigs) ; 


} 


When you have a list of the matching framebuffer configurations, you can create the 
Pbuffer using the g1XCreatePbuffer() function. The function takes a display, framebuffer 
configuration, and list of Pbuffer attributes: 


GLXPbuffer pbuffer; 
static int pbattrs[] = 
{ 
GLX_PBUFFER_WIDTH, 1024, 
GLX_PBUFFER_HEIGHT, 1024, 
1) 
}5 
pbuffer = glXCreatePbuffer(display, *configs, pbattrs) ; 


The Pbuffer attribute list consists of the GLX_PBUFFER_WIDTH and GLX_PBUFFER_HEIGHT 
values specifying the width and height of the Pbuffer. 


After you create the Pbuffer, you call the g1xCreateNewContext() function to create a 
context based on the framebuffer configuration for the Pbuffer, specifying a value of True 
for the fifth parameter for a direct rendering context: 


GLXContext context; 


context = glXCreateNewContext(display, *configs, GLX_RGBA_BIT, @, False); 
glXMakeCurrent(display, pbuffer, context) ; 


You can then draw into the pixmap using OpenGL functions and read the results back 
using the glReadPixels() function. Listing 15.6 shows a variation of the previous sample 
program that creates a Pbuffer, draws a cube, reads the image using glReadPixels(), and 
writes the result to a PPM image file called pbuffer .ppm. 


LISTING 15.6 Pbuffer Sample Program 
/* 

* Include necessary headers... 

to 


#include <stdio.h> 
#include <stdlib.h> 
#include <X11/Xlib.h> 
#include <X11/Xatom.h> 
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LISTING 15.6 Continued 


#include <GL/glx.h> 


#include <GL/gl. 


/* 

* Globals... 
*f 

float 


int 


/* 
* Functions... 
ef 


void 


/* 


h> 


CubeRotation[3], 
CubeRate[3] ; 
CubeWidth, 
CubeHeight; 


DisplayFunc(void) ; 


/* 
/* 
/* 
/* 


Rotation of cube */ 
Rotation rate of cube */ 
Width of window */ 
Height of window */ 


* ‘main()' - Main entry for example program. 


| 


int 
main(int argc, 


char *argv[]) 


GLXContext 
Display 
GLXPbuf fer 
int 
GLXFBConfig 
FILE 

int 

unsigned char 
static int 


context; 
*display; 
pbuffer; 
nconfigs; 
*configs; 
*fp; 
Y; 
pixels[3072]; 
attributes[] = 
{ 

GLX_RGBA, 


/* 
/* 
f* 


/* 
{* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


GLX_RED_SIZE, 8, 


0 - Exit status */ 
I - Number of command-line args */ 
I - Command-line args */ 


OpenGL context */ 

X display connection */ 

Pbuffer */ 

Number of configurations */ 

GLX framebuffer configuration */ 
PPM file pointer */ 

Current row */ 

One line of RGB pixels */ 

OpenGL attributes */ 


Offscreen Rendering 


LISTING 15.6 Continued 


GLX_GREEN SIZE, 8, 
GLX_BLUE_SIZE, 8, 
GLX_DEPTH_SIZE, 16, 


Q, /* Save space for GLX_DOUBLEBUFFER */ 
Q 
}5 
static int pbattrs[] = /* Pbuffer attributes */ 
{ 


GLX_PBUFFER_WIDTH, 1024, 
GLX_PBUFFER_HEIGHT, 1024, 


) 
}; 
/* 
* Open a connection to the X server... 
¥y, 


display = XOpenDisplay(getenv("DISPLAY")); 
/* 
* Get a matching framebuffer configuration... 


eT, 


configs = glxChooseFBConfig(display, DefaultScreen(display), attributes, 


&nconfigs) ; 
if (!configs) 
{ 
attributes[3] = GLX_DOUBLEBUFFER; 
configs = glXChooseFBConfig(display, DefaultScreen(display), 
attributes, &nconfigs) ; 
} 
if (!configs) 
{ 
puts("No OpenGL framebuffer configurations available!"); 
return (1); 
} 
/* 


* Create the Pbuffer... 
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LISTING 15.6 Continued 
*] 
pbuffer = glXCreatePbuffer(display, *configs, pbattrs); 
/* 
* Create the OpenGL context... 
| 


context = glXCreateNewContext(display, *configs, GLX_RGBA_BIT, 0, True); 
glXMakeCurrent(display, pbuffer, context); 


{* 
* Setup remaining globals... 
wif 
CubeWidth = 1024; 
CubeHeight = 1024; 
CubeRotation[0] = 45.0f; 
CubeRotation[1] = 45.0f; 
CubeRotation[2] = 45.0f; 
CubeRate[Q] = 1.0f; 
CubeRate[1] = 1.0f; 
CubeRate[2] = 1.0f; 
/* 
* Draw a cube... 
| 
DisplayFunc(); 
/* 
* Read back the RGB pixels and write the result as a PPM file. 
wf 


if ((fp = fopen("pbuffer.ppm", "wb")) == NULL) 
perror("Unable to create pbuffer.ppm") ; 
else 
{ 
/* 
* Write a PPM image from top to bottom... 
me 


LISTING 15.6 Continued 


Offscreen Rendering 


fputs("P6\n1024 1024 255\n", fp); 


for (y = 1023; y >= @; y --) 
{ 


glReadPixels(®, y, 1024, 1, GL_RGB, GL_UNSIGNED BYTE, pixels); 


fwrite(pixels, 1024, 3, fp); 
} 


fclose(fp); 
} 


/* 


* Destroy all resources we used and close the display... 


=f 


glxDestroyContext(display, context) ; 
glxXDestroyPbuffer(display, pbuffer) ; 
XCloseDisplay (display) ; 


/* 


Of, 
Of, 
Of, 
OF, 
Of, 
Of, 
Of, 


Looping vars */ 


.Of }, 
.Of }, 
OF }, 
Of }, 


/* 
/* 
/* 
/* 
/* 
/* 
/* 


return (0); 
} 
/* 
* 'DisplayFunc()' - Draw a cube. 
sl / 
void 
DisplayFunc(void) 
{ 
int b Hae Fe 
static const GLfloat corners[8][3] = /* Corner vertices 
{ 
{ 1.0f, 1 
{. B@hy == 
{ =1Of, =1 
{Oty 1 
C AOt 4 
f A505 <-'4 
{ =4,.0f;, =1 
{ =1.0f,, 1 


Of, 


«, Jin tp Awe 
eee ee ae a a oe ee 


/* 


atl 


Front top right */ 
Front bottom right */ 
Front bottom left */ 
Front top left */ 
Back top right */ 
Back bottom right */ 
Back bottom left */ 
Back top left */ 
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LISTING 15.6 Continued 


hs 
static const int sides[6][4] = /* Sides */ 
{ 
{05 15. 25° 33, /* Front */ 
{ 4, 5, 6, 7 }, /* Back */ 
{05 1554 /* Right */ 
{2 Soot Cohis f= Lett: */ 
{ 0, 3, 7, 4}, /* Top */ 
fds 225. 6:6) } /* Bottom */ 
}5 
static const GLfloat colors[6][3] = /* Colors */ 
{ 
{ 1.0f, 0.0f, 0.Of }, /* Red */ 
{ 0.0f, 1.0f, 0.O0f }, /* Green */ 
{ 1.0f, 1.0f, 0.0f }, /* Yellow */ 
{ 0.0f, 0.0f, 1.0f }, /* Blue */ 
{ 1.0f, 0.Of, 1.0f }, /* Magenta */ 
{ 0.0f, 1.0f, 1.0f } /* Cyan */ 
}5 
/* 
* Clear the window... 
sl 


glViewport(®, @, CubeWidth, CubeHeight) ; 
glClearColor(0.0f, 0.0f, 0.0f, 0.0f); 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 


/* 
* Setup the matrices... 
Ed 


glMatrixMode(GL_PROJECTION) ; 

glLoadidentity(); 

gl0rtho(-2.0f, 2.0f, 
-2.0f * CubeHeight / CubeWidth, 2.0f * CubeHeight / CubeWidth, 
-2.0f, 2.0f); 


glMatrixMode (GL_MODELVIEW) ; 
glLoadidentity(); 
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LISTING 15.6 Continued 


glRotatef(CubeRotation[®], 1.0f, @.0f, 0.0f); 
glRotatef(CubeRotation[1], 0.0f, 1.0f, 0.0f); 
glRotatef(CubeRotation[2], 0.0f, 0.0f, 1.0f); 


/* 
* Draw the cube... 
Hf 


glEnable(GL_DEPTH_TEST); 
g1Begin(GL_QUADS) ; 


for (i = 0; i < 6; i ++) 
{ 
glColor3fv(colors[i]); 
Tor Cj =605 I< 451 eat) 
glVertex3fv(corners[sides[i][j]]); 


} 


glEnd(); 


Using the Motif Library 


The Motif library is one of the older toolkits used on UNIX/Linux and is still the standard 
used for applications developed solely for commercial versions of UNIX. Motif is based on 
the X Intrinsics (Xt) library, which provides the core support for several other toolkits such 
as the Athena toolkit (Xaw), the 3D Athena toolkit (Xaw3d), and the neXtaW toolkit, 
which provides a NextStep look and feel. 


Two OpenGL widgets are available: one for generic Xt-based toolkits called 
GLwDrawingArea and one specifically integrated with Motif called GLwMDrawingArea. Both 
are functionally equivalent, so we will create an example based on the Motif toolkit and 
GLwMDrawingArea widget. 


The OpenGL widgets are provided in a separate library called GLw. You include them in 
your application by using the -1GLw linker option. A typical link command for a Motif- 
based OpenGL application looks like the following: 


gcc -O myprogram myprogram.o -1GLw -1GL -1Xm -1Xt -1Xext -1X11 
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GLwDrawingArea and GLwMDrawingArea: The OpenGL Widgets 


Like most Motif and Xt widgets, the OpenGL widgets use abbreviated header filenames. 
The include file for the generic GlwDrawingArea widget is <GL/GLwDrawA.h>, and the Motif 
widget is <GL/GLwMDrawA.h>. After you include the appropriate header file, you use the 
XtVaCreateManagedWidget function to create the OpenGL widget, as follows: 


widget = XtVaCreateManagedWidget ( 
"name", 
glwMDrawingAreaWidgetClass, 
parent, 
GLwNrgba, True, 
GLwNdoublebuffer, True, 
GLwNdepthSize, 16, 
.. other resource arguments as needed ... 
NULL) ; 


The first argument is the resource name of the widget; it can be used to associate addi- 
tional X resources with the widget, including the OpenGL resources. 


The second argument specifies the widget class; glwMDrawingAreaWidgetClass specifies the 
Motif OpenGL widget. You use glwDrawingAreaWidgetClass for the generic Xt OpenGL 
widget. 


The third argument specifies the parent widget, which is normally a manager widget like 
XmForm. 


The remaining arguments specify widget resources in name/value pairs along with a trail- 
ing NULL pointer to specify the end of the resource argument list. Normally, Motif and Xt 
applications use hard-coded resources for widget configuration and resource files and fall- 
back resources for labels and basic look-and-feel preferences. In this case, we specify the 
OpenGL visual attributes so that the correct visual will be used for double-buffered RGB 
(TrueColor) drawing. Table 15.2 lists the available OpenGL widget resources. Most directly 
correspond to the GLX attributes and are used to construct a GLX attribute list. The 
GLwNattribList resource specifies the GLX attribute list directly. 


TABLE 15.2 OpenGL Widget Resources 


Resource Name Resource Type Corresponding GLX Attribute from Table 15.1 
GLwNaccumAlphaSize int GLX_ACCUM_ALPHA_SIZE 

GLwNaccumBlueSize int GLX_ACCUM_BLUE_SIZE 

GLwNaccumGreenSize int GLX_ACCUM_GREEN_SIZE 

GLwNaccumRedSize int GLX_ACCUM_RED_SIZE 

GLwNalphaSize int GLX_ALPHA_SIZE 

GLwNattribList int * None; specifies the GLX attribute list directly 


GLwNauxBuf fers boolean GLX_AUX_BUFFERS 


Resource Name 


GLwNblueSize 
GLwNbufferSize 
GLwNdepthSize 
GLwNdoublebuffer 
GLwNgreenSize 
GLwNlevel 
GLwNredSize 
GLwNrgba 
GLwNstencilSize 
GLwNstereo 


Resource Type 


Using the Motif Library 


Corresponding GLX Attribute from Table 15.1 


Callbacks 


int GLX_BLUE_SIZE 
int GLX_BUFFER_SIZE 
int GLX_DEPTH_SIZE 
boolean GLX_DOUBLEBUFFER 
int GLX_GREEN_SIZE 
int GLX_LEVEL 

int GLX_RED_SIZE 
boolean GLX_RGBA 

int GLX_STENCIL_SIZE 
boolean GLX_STEREO 


After you create the widget, you must associate several callbacks with one or more callback 
functions in your application. Table 15.3 lists the callbacks that the OpenGL widgets 


define. 


TABLE 15.3 OpenGL Widget Callback Resources 


Resource Name 


GLwNexposeCallback 
GLwNginitCallback 
GLwNinputCallback 
GLwNresizeCallback 


Description 


The redraw callback 

The initialization callback 

The callback for mouse and keyboard input 
The callback for widget resizes 


OpenGL widget callbacks take three arguments: the widget pointer, the user data pointer, 
and a pointer to the GLwDrawingAreaCallbackStruct data structure. Table 15.4 shows the 
members of the structure. You can use the reason member of this structure to handle all 
types of callbacks using a single function. 


TABLE 15.4 GLwDrawingAreaCallbackStruct Members 


Name Type 
event XEvent * 
height Dimension 
reason int 

width Dimension 


Description 


The X event associated with the input or expose callback 

The new height of the widget for expose and resize callbacks 

The reason for the callback: GLwCR_EXPOSE, GLwCR_GINIT, GLwCR_INPUT, 
or GLwCR_RESIZE 

The new width of the widget for expose and resize callbacks 


The GLwNexposeCallback Callback 
The GLwNexposeCallback callback function handles redrawing the widget when the 
window manager reports that all or part of the widget is exposed and needs to be drawn. 
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Typically, this function sets the current OpenGL context and draws in the widget. The 
width and height members of the callback structure contain the current width and height 
of the widget, and the event member contains any X expose event data that can be used 
to see whether additional expose events follow or to limit the redraw to the area that 
needs it. 


The GLwNginitCallback Callback 

The GLwNginitCallback callback function handles any initialization of the OpenGL 
widget. Typically, this function creates the OpenGL context, loads textures and fonts, and 
initializes display lists for common display elements. 


The GLwNvisualInfo resource can be queried by the callback to create the OpenGL 
context. The following code creates an OpenGL context using the resource value: 


Widget application_shell; 
Widget drawing area; 
XVisualInfo *info; 
GLXcontext context; 


XtVaGetValues(drawing_area, GLwNvisualInfo, &info, NULL); 
context = glXCreateContext (XtDisplay(application_shell), info, 
NULL, GL_TRUE) ; 


This resource and the OpenGL window for the widget are not created until your callback 
function is called. 


The GLwNinputCallback Callback 

The GLwNinputCallback callback function handles user input in the form of button clicks, 
mouse motion, and keyboard interaction. The event member of the callback data points to 
the ButtonPress, ButtonRelease, MotionNotify, KeyPress, or KeyRelease event that trig- 
gered the callback. 


The GLwNresizeCallback Callback 

The GLwNresizeCallback callback function is called whenever the application or user 
resizes the OpenGL widget. The width and height members of the callback data contain 
the new width and height of the widget and can be used to track changes to the size of 
the widget. An expose callback with the same information will follow a resize callback, so 
many applications do not need to use the resize callback. 


Functions 

The GLw library provides two helper functions that work with both of the OpenGL widgets. 
The GLwDrawingAreaMakeCurrent() function sets the current OpenGL context for the 
widget and must be called before drawing to the widget: 
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GLwDrawingAreaMakeCurrent (drawing area, context); 


When you are done drawing in a double-buffered widget, call the 
GLwDrawingAreaSwapBuffers() function to swap the front and back buffers: 


GLwDrawingAreaSwapBuf fers (drawing area) ; 


Putting It All Together 


Listing 15.7 shows a Motif version of the xlibfonts example presented in Listing 15.4, 
providing identical output. The program starts by creating an Xt “application shell,” 
which includes the main window. It then adds a Motif XmForm widget to manage the 
OpenGL widget and the OpenGL widget itself: 


Widget CubeShell1; /* Application shell */ 
XtAppContext CubeContext; /* Application context */ 
Widget CubeGLArea; /* OpenGL drawing area */ 
Widget form; /* Form management widget */ 
XtAppContext context; /* Application context */ 
static char *fallback[] = /* Fallback resources */ 
{ 
"Motif .geometry: 400x400", 
NULL 
}5 
/* 
* Initialize the application window and manager widgets... 
=] 


CubeShell = XtVaAppInitialize( 
&CubeContext, "Motif", NULL, 0, &argc, argv, 


fallback, 

XmNtitle, “Motif Example", 
XmNiconName, "Motif", 

NULL) ; 


form = XtVaCreateManagedWidget ( 
“form", xmFormWidgetClass, CubeShell, 
NULL) ; 


/* 
* Create the OpenGL drawing area... 
dl f 
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CubeGLArea = XtVaCreateManagedWidget ( 
“drawingArea", glwMDrawingAreaWidgetClass, form, 


GLwNrgba, True, 
GLwNdoublebuffer, True, 
GLwNdepthSize, 16, 


XmNtopAttachment, XmATTACH_FORM, 
XmNbottomAttachment, XmATTACH_FORM, 
XmNleftAttachment, XmATTACH_FORM, 
XmNrightAttachment, XmATTACH_FORM, 
NULL) ; 


The OpenGL widget is attached to the sides of the form, causing it to occupy the entire 
window. In a typical application with a menu bar, you would probably attach the top of 
the OpenGL widget to the menu bar instead. 


After you create the widgets, you set the callback functions to use for the OpenGL widget: 


XtAddCallback(CubeGLArea, GLwNexposeCallback, 
(XtCallbackProc)DisplayCB, NULL); 
XtAddCallback(CubeGLArea, GLwNginitCallback, 
(XtCallbackProc)InitCB, NULL); 
XtAddCallback(CubeGLArea, GLwNresizeCallback, 
(XtCallbackProc)ReshapeCB, NULL); 
XtAddCallback(CubeGLArea, GLwNinputCallback, 
(XtCallbackProc)InputCB, NULL); 


Finally, you “realize” the application shell to show the window and call the 
XtAppMainLoop() function to start the application event loop: 


XtRealizeWidget(CubeShel11) ; 
XtAppMainLoop(CubeContext) ; 


The callback functions use the same functions as the xlibfonts example to initialize the 
OpenGL context and font, draw the cube and text, and handle mouse input. A new 
TimeOutCB() function is used to rotate the cube once every 20 milliseconds and is regis- 
tered via XtAppAddTimeOut ( ): 


void 

TimeOutCB (void) 

{ 
CubeRotation[@] += CubeRate[Q]; 
CubeRotation[1] += CubeRate[1]; 
CubeRotation[2] += CubeRate[2]; 
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if (CubeRate[®] || CubeRate[1] || CubeRate[2]) 
XmRedisplayWidget (CubeGLArea) ; 


XtAppAddTimeOut(CubeContext, 20, 
(XtTimerCallbackProc)TimeOutCB, NULL); 


The XmRedisplayWidget() function tells the OpenGL widget to redraw itself and can be 
used by applications to update their display based on new, possibly asynchronous data or 


user input. 


LISTING 15.7 The Motif Sample Source Code 


/* 


* Include necessary headers... 


39 | 


#include <stdio.h> 
#include <stdlib.h> 
#include <Xm/Xm.h> 
#include <Xm/Form.h> 
#include <GL/GLwMDrawA. h> 


/* 
* Globals... 
= 
float CubeRotation[3], /* Rotation of cube */ 
CubeRate[3]; /* Rotation rate of cube */ 
int CubeMouseButton, /* Button that was pressed */ 
CubeMousex, /* Start X position of mouse */ 
CubeMouseyY; /* Start Y position of mouse */ 
int CubeWidth, /* Width of window */ 
CubeHeight; /* Height of window */ 
GLuint CubeFont; /* Display list base for font */ 
Widget CubeShell; /* Application shell */ 
XtAppContext CubeContext; /* Application context */ 
Widget CubeGLArea; /* OpenGL drawing area */ 
GLxXContext CubeGLContext; /* OpenGL drawing context */ 
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LISTING 15.7. Continued 


/* 
* Functions... 
rch 


void DisplayCB(void) ; 


void InitCB(Widget w, void *ud, GLwDrawingAreaCallbackStruct *cd); 
void InputCB(Widget w, void *ud, GLwDrawingAreaCallbackStruct *cd); 
void ReshapeCB(Widget w, void *ud, GLwDrawingAreaCallbackStruct *cd); 


void TimeOutCB(void) ; 


/* 


* ‘'main()' - Main entry for example program. 


| 


int 
main(int argc, 
char *argv[]) 

{ 
Widget form; 
XtAppContext context; 
static char *fallback[] = 

{ 


/* 
/* 
[* 


/* 
/* 
/* 


“Motif .geometry: 


NULL 
}; 


/* 


0 - Exit status */ 
I - Number of command-line args */ 
I - Command-line args */ 


Form management widget */ 
Application context */ 


Fallback resources */ 


400x400", 


* Initialize the application window and manager widgets... 


*/ 


CubeShell = XtVaAppInitialize( 


&CubeContext, "Motif", NULL, ®, &argc, argv, 


fallback, 


XmNtitle, “Motif Example", 


XmNiconName, "Motif", 
NULL) ; 
form = XtVaCreateManagedWidget ( 


"form", xmFormWidgetClass, CubeShell, 


NULL) ; 
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/* 
* Create the OpenGL drawing area... 
vil 


CubeGLArea = XtVaCreateManagedWidget ( 
"drawingArea", glwMDrawingAreaWidgetClass, form, 


GLwNrgba, True, 
GLwNdoublebuffer, True, 
GLwNdepthSize, 16, 


XmNtopAttachment, XmATTACH_FORM, 
XmNbottomAttachment, XmATTACH_FORM, 
XmNleftAttachment, | XmATTACH_FORM, 
XmNrightAttachment, XmATTACH_FORM, 


NULL) ; 
/* 
* Set callbacks and timeout processing... 
if 


XtAddCallback(CubeGLArea, GLwNexposeCallback, 
(XtCallbackProc)DisplayCB, NULL); 
XtAddCallback(CubeGLArea, GLwNginitCallback, 
(XtCallbackProc)InitCB, NULL); 
XtAddCallback(CubeGLArea, GLwNresizeCallback, 
(XtCallbackProc)ReshapeCB, NULL) ; 
XtAddCallback(CubeGLArea, GLwNinputCallback, 
(XtCallbackProc)InputCB, NULL); 


/* 

* Setup remaining globals... 
lf 

CubeWidth = 400; 
CubeHeight = 400; 


CubeRotation[0] = 45.0f; 
CubeRotation[1] = 45.0f; 
CubeRotation[2] = 45.0f; 


CubeRate[0] = 1.0f; 
CubeRate[1] = 1.0f; 
CubeRate[2] = 1.0f; 
{* 


* Loop forever.. 
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LISTING 15.7 Continued 


is 


XtRealizeWidget (CubeShel1l) ; 
XtAppMainLoop(CubeContext) ; 


return (0); 


/* 
* 'DisplayCB()' - Display callback. 
*/ 


ar nN WO 


void 
DisplayCB(void) 
:t 
int a 
XVisualInfo *info; 
XFontStruct *font; 
static const GLfloat corners[8][3] 
{ 
Ce TOT le 
VOT, = Te 
{°=1 OF 5. = As 
{ =1.0f, 74. 
{i TOF. . The 
{ 40%) =; 
C4 OR 1s 
{108 1. 
}; 
static const int sides[6][4] = 
{ 
{ 0, 1, 2, 
{ 4, 6, 6, 
{ 0, 1, 5, 
{ 2, 3, 7, 
{ 0, 3, 7, 
{ 1, 2, 6, 
}3 
static const GLfloat colors[6][3] 
{ 


/* Looping vars */ 
/* Drawing area visual */ 
/* X font information */ 


/* 
[* 
/* 
/* 
/* 
/* 
/* 
/* 


{* 
/* 
/* 
i* 
/* 


= /* Corner vertices 
Of, 1.0f }, 
Of, 1.0f }, 
Of, 1.0f }, 
Of, 1.0f }, 
Of, -1.0f }, 
Of, -1.0f }, 
Of, -1.0f }, 
Of, -1.0f } 
/* Sides */ 

}; 

}, 

}; 

}s 

}; 

} 


/* Colors */ 


{ 1.0f, 0.0f, 0.0f }, 
{ 0.0f, 1.0f, 0.0f }, 


/* 


[* 
/* 


*/ 


Front top right */ 
Front bottom right */ 
Front bottom left */ 
Front top left */ 
Back top right */ 
Back bottom right */ 
Back bottom left */ 
Back top left */ 


Front */ 
Back */ 
Right */ 
Left */ 
Top */ 
Bottom */ 


Red */ 
Green */ 


Using the Motif Library 849 


LISTING 15.7 Continued 


{ 1.0f, 1.0f, 0.OFi }, /* Yellow */ 
{ 0.0f, 0.0f, 1.0f }, /* Blue */ 
{ 1:08, C208; IO }, /* Magenta */ 
{ 0.0f, 1.0f, 1.0f } /* Cyan */ 
}5 
/* 
* Clear the window... 
‘if 


glViewport(®, @, CubeWidth, CubeHeight) ; 
glClearColor(0.0f, 0.0f, 0.0f, 0.0f); 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); 


/* 
* Setup the matrices... 
*/ 


SL 


glMatrixMode(GL_PROJECTION) ; 

glLoadidentity() ; 

glOrtho(-2.0f, 2.0f, 
-2.0f * CubeHeight / CubeWidth, 2.0f * CubeHeight / CubeWidth, 
-2.0f, 2.0f); 


glMatrixMode(GL_MODELVIEW) ; 

glLoadIdentity(); 

glRotatef(CubeRotation[®], 1.0f, @.0f, 0.0f); 
glRotatef(CubeRotation[1], @.0f, 1.0f, 0.0f); 
glRotatef(CubeRotation[2], 0.0f, 0.0f, 1.0f); 


/* 
* Draw the cube... 
1 


glEnable(GL_DEPTH_TEST) ; 
glBegin(GL_QUADS) ; 
for (i = 0; i < 6; i ++) 


{ 
glColor3fv(colors[i]); 


FORM (SP S20 5-9 S444) 
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LISTING 15.7 Continued 


glVertex3fv(corners[sides[i][j]]); 


glEnd(); 


/* 


* Draw lines coming out of the cube... 


*/ 
glColor3f(1.0f, 1.0f, 1.0f); 


glBegin(GL_LINES) ; 


glVertex3f(@.0f, 0.0f, -1.5f); 
glVertex3f(0.0f, @.0f, 1.5f); 


glVertex3f(-1.5f, @.Of, 0.0f); 
glVertex3f(1.5f, 0.0f, 0.0f); 


glVertex3f(0.0f, 1.5f, 0.0f); 
glVertex3f(@.0f, -1.5f, 0.0f); 


glEnd(); 


{* 


* Draw text for each side... 
| 


glPushAttrib(GL_LIST_BIT) ; 


glListBase(CubeFont - ' '); 


glRasterPos3f(@.0f, 0.O0f, -1.5f); 
glCallLists(4, GL_BYTE, "Back"); 


glRasterPos3f(0.0f, 0.0f, 1.5f); 
glCallLists(5, GL_BYTE, "Front"); 


glRasterPos3f(-1.5f, @.0f, 0.0f); 
glCallLists(4, GL_BYTE, "Left"); 


glRasterPos3f(1.5f, 0.0f, 0.O0f); 
glCallLists(5, GL_BYTE, "Right"); 


glRasterPos3f(0.0f, 1.5f, 0.0f); 
glCallLists(3, GL_BYTE, "Top"); 


LISTING 15.7 Continued 


glRasterPos3f(0.0f, -1.5f, 0.0f); 
glCallLists(6, GL_BYTE, “Bottom"); 
glPopAttrib(); 


j* 
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* Swap the back buffer with the front buffer... 


/ 


GLwDrawingAreaSwapBuf fers (CubeGLArea) ; 
} 


/* 
* 'InitCB()' - Initialization callback. 
sol | 
void 
InitCB (Widget We? 8 
void *ud, /* 
GLwDrawingAreaCallbackStruct *cd)/* 
{ 
XVisualInfo *info; f= 
XFontStruct *font; {* 
/* 


I - Widget */ 
I - User data */ 
I - Callback data */ 


Drawing area visual */ 
X font information */ 


* Initialize the OpenGL context for drawing... 


“el! 


XtVaGetValues(CubeGLArea, GLwNvisuallInfo, 


&info, NULL); 


CubeGLContext = glXCreateContext(XtDisplay(CubeShell), info, 
NULL, GL_TRUE) ; 


if (!CubeGLContext) 
{ 


puts("Unable to create OpenGL context!"); 


exit(1); 
} 


GLwDrawingAreaMakeCurrent(CubeGLArea, CubeGLContext) ; 


{* 
* Setup font... 
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LISTING 15.7 Continued 
*/ 


font XLoadQueryFont(XtDisplay(CubeShel1l) , 
"-*-courier-bold-r-normal--14-*-*-*-*-*-*-*") 5 


CubeFont = glGenLists(96) ; 


glXUseXFont(font->fid, ' ', 96, CubeFont); 

fe 

* Activate the timeout procedure to rotate the cube... 
sf 


XtAppAddTimeOut(CubeContext, 20, 
(XtTimerCallbackProc)TimeOutCB, NULL) ; 


} 
/* 
* 'InputCB()' - Input callback. 
a | 
void 
InputCB (Widget w, /* I - Widget */ 
void *ud:, 
/* I - User data */ 
GLwDrawingAreaCallbackStruct *cd) 
/* I - Callback data */ 
{ 
int x; /* X position */ 


y; /* Y position */ 


switch (cd->event->type) 
{ 
case ButtonPress : 
/* 
* Save the initial mouse button + position... 
*/ 


CubeMouseButton = cd->event->xbutton.button; 
CubeMouseX cd->event ->xbutton.x; 
CubeMouseY cd->event ->xbutton.y; 


LISTING 15.7 Continued 
{* 
* Zero-out the rotation rates... 
mf 


CubeRate[Q] 
CubeRate[1] 
CubeRate[2] 
break; 


Q.0f; 
Q.0f; 
Q.0f; 


case MotionNotify : 
/* 
* Get the mouse movement... 
uff 


cd->event->xmotion.x - CubeMousex; 
cd->event->xmotion.y - CubeMouseY; 


/* 

* Update the cube rotation rate based upon the mouse 
* movement and button... 

Bi 


switch (CubeMouseButton) 


{ 
case 0: /* Button 1 */ 
CubeRate[@] = 0.01f * y; 
CubeRate[1] = 0.01f * x; 
CubeRate[2] = 0.0f; 
break; 
case 1: /* Button 2 */ 
CubeRate[0] = 0.0f; 
CubeRate[1] = 0.01f * y; 
CubeRate[2] = 0.01f * x; 
break; 
default : /* Button 3 */ 
CubeRate[®] = 0.01f * y; 
CubeRate[1] = 0.0f; 
CubeRate[2] = 0.01f * x; 
break; 
} 


break; 
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LISTING 15.7 Continued 


} 
} 
/* 
* 'ReshapeCB()' - Resize callback. 
¥/ 
void 
ReshapeCB (Widget w, 
/* I - Widget */ 
void *ud, 
/* I - User data */ 
GLwDrawingAreaCallbackStruct *cd) 
/* I - Callback data */ 
{ 
/* 
* Save the current width and height... 
i | 
CubeWidth = cd->width; 
CubeHeight = cd->height; 
} 
/* 
* 'TimeOutCB()' - Rotate and redraw the cube. 
at | 
void 
TimeOutCB( void) 
{ 


CubeRotation[0] += CubeRate[Q]; 
CubeRotation[1] += CubeRate[1]; 
CubeRotation[2] += CubeRate[2]; 


if (CubeRate[®] |} CubeRate[1] |; CubeRate[2]) 
XmRedisplayWidget (CubeGLArea) ; 


XtAppAddTimeOut (CubeContext, 20, 
(XtTimerCallbackProc)TimeOutCB, NULL) ; 


Reference 


Summary 


In this chapter, we have taken the basic OpenGL principles and extended them for use in 
a Linux environment. You have leaned how to set up an appropriate visual for an applica- 
tion and how rendering contexts are handled in the Linux environment. You now also 
know how to deal with double buffered contexts. You learned how to generate and use 
bitmap fonts. Finally, we introduced using pBuffers for offscreen rendering on Linux. 


Reference 


glXChooseFBConfig 


Purpose: Gets a list of matching framebuffer configurations. 
Include File: <GL/g1x.h> 
Syntax: 


GLXFBConfig *glXChooseFBConfig(Display *dpy, int screen, const int *attribList, int 
*nelements) ; 


Description: This function finds a list of framebuffer configurations that match the 
specified GLX attributes. 

Parameters: 

*dpy The X display connection 

screen The screen to query 

*attriblist The NULL-terminated list of GLX attributes 

*nelements Pointer to an integer that will hold the number of framebuffer configura- 
tions that are pointed to 

Returns: A pointer to an array of matching framebuffer configurations or NULL if 
the X display does not support the framebuffer query. Use the XFree() 
function to free the memory used for the array. 

See Also: glxXGetFBConfigs, g1XGetVisualFromFBConfig, g1xXCreatePbuffer 

glXChooseVisual 

Purpose: Selects an X visual to use for OpenGL rendering. 

Include File: <GL/g1lx.h> 

Syntax: 


XVisualInfo *glXChooseVisual(Display *dpy, int screen, int *attribList) ; 


Description: This function finds a visual matching the specified GLX rendering 
attributes that can be used to create a window or pixmap for OpenGL 
rendering. 
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Parameters: 
*dpy The X display connection 
screen The screen number 


*attribList The zero-terminated attribute list 


Returns: A pointer to a matching X visual information structure or NULL. 
See Also: glXCreateContext, glXCreateGLXPixmap 
glXCreateContext 

Purpose: Creates an OpenGL drawing context. 

Include File: <GL/glx.h> 

Syntax: 


GLXContext glXCreateContext(Display *dpy, XVisualInfo *vis, GLXContext shareList, 
Bool direct); 


Description: This function creates a context for OpenGL rendering. The context can 
be direct-to-hardware or indirect and can share the display lists, textures, 
and so forth with other OpenGL contexts of the same type. 


Parameters: 

*dpy The X display connection 

*vis The X visual to use 

shareList An OpenGL context for sharing display lists, textures, and so on 
direct True if a direct-to-hardware context is desired; False otherwise 
Returns: A new OpenGL context or NULL if the context cannot be created. 
See Also: g1XChooseVisual, glXCreateNewContext 
glXCreateGLXPixmap 

Purpose: Creates an offscreen pixmap for OpenGL rendering. 

Include File: <GL/glx.h> 

Syntax: 


GLXPixmap glXCreateGLXPixmap(Display *dpy, XVisualInfo *vis, Pixmap pixmap) ; 


Description: This function creates a GLX pixmap that can be used to do offscreen 
rendering of OpenGL scenes. Only indirect rendering contexts may be 
used with GLX pixmaps. 


Reference 


Parameters: 

*dpy The X display connection 

*vis The X visual to use 

pixmap The X pixmap to use 

Returns: The new GLX pixmap. 

See Also: glXChooseVisual, glXCreateContext 
glXCreateNewContext 

Purpose: Creates a new OpenGL context. 


Include File: <GL/glx.h> 
Syntax: 


GLXContext glXCreateNewContext (Display *dpy, GLXFBConfig config, int renderType, 
GLXContext shareList, Bool direct); 


Description: This function creates a context for OpenGL rendering and is functionally 
equivalent to g1xXCreateContext(). The context can be direct-to-hardware 
or indirect and can share the display lists, textures, and so forth with 
other OpenGL contexts of the same type. 

Parameters: 


Display *dpy The X display connection 


config The framebuffer configuration to use 

renderType The color type of the context: GLX_RGBA_TYPE for RGBA rendering or 
GLX_COLOR_INDEX_TYPE for color indexed rendering 

shareList An OpenGL context for sharing display lists, textures, and so on 

direct True if a direct-to-hardware context is desired; False otherwise 

Returns: A new OpenGL context or NULL if the context cannot be created. 

See Also: glXChooseFBConfig, glxXCreateContext, glXDestroyContext, 
glxXGetFBConfigs 

g!XCreatePbuffer 

Purpose: Creates an offscreen pixel buffer for OpenGL rendering. 

Include File: <GL/glx.h> 

Syntax: 


GLXPbuffer glXCreatePbuffer(Display *dpy, GLXFBCOnfig config, const int 
*attribList) ; 
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Description: This function creates an offscreen pixel buffer for OpenGL rendering. The 
dimensions of the Pbuffer are specified using the GLX_WIDTH and 
GLX_HEIGHT attributes. 


Parameters: 

*dpy The X display connection 

config The framebuffer configuration 

*attribList The zero-terminated list of GLX attributes 

Returns: A new Pbuffer or NULL if it could not be created. 

See Also: glXGetFBConfigs, glXChooseFBConfigs, g1XDestroyPbuffer 
glXDestroyContext 

Purpose: Destroys an OpenGL context. 

Include File: <GL/glx.h> 

Syntax: 


void glxXDestroyContext(Display *dpy, GLXContext ctx); 


Description: This function destroys an OpenGL rendering context, freeing any system 
resources associated with it. 

Parameters: 

*dpy The X display connection 

ctx The OpenGL context 

Returns: Nothing. 

See Also: glXCreateContext 

glXDestroyGLXPixmap 

Purpose: Destroys a GLX pixmap. 


Include File: <GL/g1x.h> 
Syntax: 
void glXDestroyGLXPixmap(Display *dpy, GLXPixmap pix); 


Description: This function destroys a GLX pixmap resource. You must still destroy the 
X pixmap resource and OpenGL context separately. 

Parameters: 

*dpy The X display connection 


pix The GLX pixmap 


Reference 


Returns: Nothing. 

See Also: glXCreateGLXPixmap 
glXDestroyPbuffer 

Purpose: Destroys an offscreen pixel buffer. 
Include File: <GL/glx.h> 

Syntax: 


void glXDestroyPbuffer(Display *dpy, GLXPbuffer pbuf); 


Description: This function releases all resources used for the specified Pbuffer. 
Parameters: 

*dpy The X display connection 

pbuf The Pbuffer 

Returns: Nothing. 

See Also: g1lXCreatePbuffer 

g|XGetFBConfigs 

Purpose: Gets a list of supported framebuffer configurations. 

Include File: <GL/glx.h> 

Syntax: 


GLXFBConfig *glXGetFBConfigs(Display *dpy, int screen, int *nelements); 


Description: This function gets a list of supported framebuffer configurations for the 
specified display and screen. 


Parameters: 

*dpy The X display connection 

screen The screen to query 

*nelements Pointer to an integer that will hold the number of framebuffer configura- 
tions that are pointed to 

Returns: A pointer to an array of framebuffer configurations or NULL if the X 


display does not support the framebuffer query. Use the XFree() function 
to free the memory used for the array. 


See Also: g1lXChooseFBCOnfig, glXGetVisualFromFBConfig, gl1XCreatePbuffer 
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glXGetVisualFromFBConfig 


Purpose: Gets the X visual for a specific framebuffer configuration. 
Include File: <GL/glx.h> 
Syntax: 


XVisualInfo *gl1XGetVisualFromFBConfig(Display *dpy, GLXFBConfig config) ; 


Description: This function finds the X visual that corresponds to the given frame- 
buffer configuration. 

Parameters: 

*dpy The X display connection 

config The framebuffer configuration 

Returns: A pointer to the XVisualInfo structure containing all the X visual infor- 
mation for the given framebuffer configuration. 

See Also: g1XGetFBConfigs, glXChooseFBConfigs, glXCreatePbuffer 

glXMakeCurrent 

Purpose: Sets the current OpenGL context for rendering. 

Include File: <GL/glx.h> 

Syntax: 


Bool glXMakeCurrent(Display *dpy, GLXDrawable drawable, GLXContext ctx); 


Description: This function sets the current OpenGL context and drawable (window or 
pixmap) to use when rendering. If there are any pending OpenGL 
drawing commands on the previous context, they are flushed prior to 
changing the current context. Pass None for the drawable and NULL for the 
context arguments to flush pending OpenGL commands and release the 
current context. 


Parameters: 

*dpy The X display connection 

ctx The OpenGL context 

drawable The window or pixmap 

Returns: True if the context is set successfully; False otherwise. 


See Also: g1lXCreateContext, glXCreateNewContext, glXSwapBuffers 


Reference 


glXSwapBuffers 

Purpose: Swaps the front and back display buffers. 
Include File: <GL/g1x.h> 

Syntax: 


void glXSwapBuffers(Display *dpy, GLXDrawable drawable) ; 


Description: This function swaps the back buffer with the front buffer, synchronizing 
with the vertical retrace of the screen as necessary. 

Parameters: 

*dpy The X display connection 

drawable The window or pixmap 

Returns: Nothing. 

See Also: glxXCreateContext, glXCreateNewContext, glXMakeCurrent 

glXUseXFont 

Purpose: Creates a collection of bitmap display lists. 

Include File: <GL/g1x.h> 

Syntax: 


void glXUsexXFont(Font font, int first, int count, int listbase) ; 


Description: 


Parameters: 
font 

first 
count 
listbase 
Returns: 
See Also: 


This function creates count display lists containing bitmaps of characters 
in the specified font. You allocate the display lists for the bitmaps using 
the glGenLists() function. 


Specifies the font to use 

Specifies the first character in the font to use 

Specifies the number of characters to use from the font 
Specifies the first display list to use as returned by glGenLists() 
Nothing. 

glXCreateContext 
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PART Ill 


OpenGL: The Next 
Generation 


Now we come to what I feel is the most exciting part of the 
book—and what is perhaps the most exciting development in 
PC 3D graphics since hardware-accelerated Transform and 
Lighting. The 3D pipeline that OpenGL uses is pretty much the 
standard pipeline for creating real-time 3D graphics, regardless 
of which API you are using. However, graphics techniques have 
evolved to the point that the design of the pipeline has reached 
its full potential. True photo-realistic rendering requires a great 
deal more processing applied per vertex, or even to the frag- 
ments rendered between vertices. 


To increase realism and extend graphics beyond what is possi- 
ble with the standard pipeline, vendors have designed their 
hardware to be more flexible and allow not only the processing 
of a fixed set of commands and state variables, but also the 
actual execution of graphics code on their now renamed 
Graphics Processing Units (GPUs). The programmable pipeline 
is perhaps the single biggest development in commodity graph- 
ics that we will see in our careers. One vendor calls it 
“Cinematic Computing,” and that description is not far off the 
mark. We can now approach in real-time the photo-realistic 
effects that used to take hours or days to create. OpenGL, too, 
has evolved to meet this new era. 


The following chapters take you through some of the more 
recent innovations in 3D graphics: from finer grained control of 
graphics processing memory to extended buffer capabilities and 
finally to a full-featured graphics programming language 
executed by the graphics hardware. 


CHAPTER 16 


Buffer Objects: It’s Your Video 
Memory; You Manage It! 


by Benjamin Lipchak 
WHAT YOU'LL LEARN IN THIS CHAPTER: 
How To Functions You'll Use 
Create, bind to, and delete buffer objects glGenBuf fers/glBindBuffer/glDeleteBuffers 
Send data into a buffer object indirectly glBufferData/glBufferSubData 
Write data into a buffer object directly glMapBuf fer /glUnmapBuf fer 


Graphics cards today have nearly as much memory as the rest of the system they’re 
plugged into. The amount of graphics card memory tends to at least be within an order of 
magnitude, say 25%, of the amount of system memory. That’s quite a resource to exploit— 
or to waste by not making the best use of it. 


Video memory has traditionally been used for storing the following: 
¢ Front buffers (what you see on the screen) 
¢ Back buffers (what you don’t see when double-buffering) 
e¢ Depth buffers (for hidden surface removal) 


¢ Other per-pixel storage, such as stencil planes, overlay planes, and so on 


Even at high resolutions and color depths, such as 1920x1280 and 32 bits per pixel, graph- 
ics consume only in the ballpark of 25 to 40MB. Depending on your available video 
memory, that can leave hundreds of megabytes at your disposal. 


This extra space is most often used to cache texture maps so they don’t have to be contin- 
ually transmitted from system memory to the graphics card every time a new texture is 
used. Instead, they are kept locally in video memory so they’re ready when needed. When 
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the texture cache becomes full, old textures that haven’t been used recently are evicted to 
make room for new textures. 


Some OpenGL implementations also attempt to cache geometry data in video memory, 
such as that present in display lists or vertex arrays. Unfortunately, the driver doesn’t 
know how often the geometry is going to change or how much total geometry there’s 
going to be. For vertex arrays, it doesn’t know when the data in the arrays has actually 
been changed by the application. Only the application knows all this information, so if 
the driver bothers to try at all, the best it can do is guess, and that’s not enough to guaran- 
tee optimal performance. 


Extensions such as GL_EXT_compiled_vertex_array, GL_EXT_draw_range_elements, 
GL_NV_vertex_array_range, and GL_ATI_vertex_array_object have been introduced over 
the years to attempt to supply the driver with some of this information. This progress has 
culminated in a single extension, GL_ARB_vertex_buffer_object, which hands over full 
control to the application when it comes to storing its geometry in local video memory 
for optimal rendering performance. This extension was promoted into OpenGL 1.5 as a 
core feature. 


Figure 16.1 illustrates the different types of data that share, and in fact compete for, local 
video memory on the graphics card. 


Video memory 


FIGURE 16.1 A variety of data is stored in local video memory for quick access by the 
Graphics Processing Unit (GPU), saving a trip to system memory. 


First, You Need Vertex Arrays 


First, You Need Vertex Arrays 


Buffer objects are repositories for storing data in local video memory. You can store 
anything you want in there and read it back later. If you want to store your grocery list in 
there, you’re free to do that. But the only useful things to store in there are vertex arrays 
and array indices. You can clue OpenGL in on the fact that your vertex arrays live in a 
buffer object, at which point they become blazingly fast vertex arrays. 


First, though, you need your vertex arrays. If your application uses immediate mode 
(g1Begin/glEnd pairs), you can’t take advantage of buffer objects without first switching 
over to the vertex array paradigm, discussed in Chapter 11, “It’s All About the Pipeline: 
Faster Geometry Throughput.” When you have vertex arrays working, putting them into 
buffer objects is relatively easy. It also makes before and after performance comparisons 
straightforward and gratifying! 


For our sample program, we’ll construct vertex arrays with the geometry for some sphere- 
shaped particle clouds. The more of a geometry burden we can introduce, the more 
improvement we'll see when we get around to accelerating them. So let's lay on the 
vertices! 


The number of particles per sphere is configurable. If your OpenGL implementation 
cannot handle the number of spheres defined here, or if it eats them for breakfast and 
wants more, just change this constant: 


GLint numSphereVertices = 30000; 


Generating the Spherical Particle Clouds 

We need some geometry for this program, but we don’t want to waste space in our code to 
load anything fancy, nor do we want to waste time explaining it. So we'll settle for some- 
thing simple to generate, but moderately interesting: particle cloud spheres. 


We've already decided how many vertices we want, set by the constant shown in the 
preceding section. We’ll just scatter these points randomly across the surface of a sphere. 
Sounds complicated, right? Not really. All we have to do is generate a random point in 
space. We take the vector between this random point and the origin (0,0,0) and normalize 
it to a unit vector. It now represents a point 1 unit away from the origin in some random 
direction. Figure 16.2 illustrates the normalization of the random vectors. Repeat 30,000 
times, and we have a sphere-shaped cloud of particles. 
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FIGURE 16.2 Random vectors are normalized onto the surface of a unit sphere. 


Here’s the code: 


for (i = 0; i < numSphereVertices; i++) 


{ 
GLfloat r1, r2, r3, scaleFactor; 


// pick a random vector 

r1 = (GLfloat)(rand() - (RAND _MAX/2)); 
r2 = (GLfloat)(rand() - (RAND _MAX/2)); 
r3 = (GLfloat)(rand() - (RAND_MAX/2)); 


// determine normalizing scale factor 
scaleFactor = 1.0f / sqrt(ri*r1 + r2*r2 + r3*r3); 


sphereVertexArray[ (i*3)+0] 
sphereVertexArray[ (i*3)+1] 
sphereVertexArray[ (i*3) +2] 


r1 * scaleFactor; 
r2 * scaleFactor; 
r3 * scaleFactor; 


First, You Need Vertex Arrays 


Enabling the Vertex Arrays 


We have the data prepared. Now we must enable the arrays and set the array pointers so 
that OpenGL will know where to find the geometry when rendering: 


glNormalPointer(GL_FLOAT, ®, sphereVertexArray) ; 
glVertexPointer(3, GL_FLOAT, ®, sphereVertexArray) ; 


glEnableClientState(GL_NORMAL_ARRAY) ; 
glEnableClientState (GL_VERTEX_ARRAY) ; 


Notice that we’re enabling two arrays: one for the vertex position, but also one for the 
vertex normal. Normals make lighting possible, and it just so happens that for a unit 
sphere (where radius is 1) at the origin, the position is the same as the normal! So we can 
reuse the same data for both arrays. 


Figure 16.3 visually depicts data in our vertex array. 


FIGURE 16.3 Our vertex array data includes random positions that will also serve as surface 
normals. 


More Spheres, Please! 


Thirty thousand vertices might sound like a lot, but to bring our OpenGL implementation 
to its knees, we’re going to have to throw it a bit more geometry still. So let’s draw a 3x3x3 
cube of spheres and set a different color for each cube. As demonstrated in Listing 16.1, we 
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can reuse the same vertex arrays, just changing the modelview matrix to individually 
resize and locate each sphere in between calls to g1DrawArrays. 


LISTING 16.1 Sphere Vertex Array Drawn 27 Times 


// Called to draw scene 
void RenderScene (void) 


{ 


static GLTStopwatch stopWatch; 
static int frameCounter = Q; 


// Get initial time 
if (frameCounter == 0) 
gltStopwatchReset (&stopWatch) ; 


frameCounter++; 

if (frameCounter == 100) 

{ 
frameCounter = Q; 
fprintf(stdout, "FPS: %f\n", 100.0f / gltStopwatchRead(&stopWatch) ) ; 
gltStopwatchReset (&stopWatch) ; 


// Track camera angle 

glMatrixMode(GL_PROJECTION) ; 

glLoadIdentity(); 

gluPerspective(45.0f, 1.0f, 10.0f, 10000.0f); 

glMatrixMode(GL_MODELVIEW) ; 

glLoadiIdentity(); 

gluLookAt(cameraPos[0], cameraPos[1], cameraPos[2], 
Q.O0f, O.Of, O.Of, O.Of, 1.0f, 0.0f); 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH BUFFER BIT); 


if (animating) 

{ 
RegenerateSphere(); 
SetRenderingMethod() ; 


// Draw objects in the scene 
DrawModels(); 


// Flush drawing commands 
glutSwapBuffers() ; 
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LISTING 16.1 Continued 
glutPostRedisplay(); 


frameCounter++; 
if (frameCounter == 100) 


{ 
long thisTime; 


frameCounter = 0; 

_ftime(&timeBuffer) ; 

thisTime = (timeBuffer.time * 1000) + timeBuffer.millitm; 
fprintf(stdout, "FPS: %f\n", 100.0f * 1000.0f / (thisTime - lastTime)); 
lastTime = thisTime; 


// Track camera angle 

glMatrixMode(GL_PROJECTION) ; 

glLoadIdentity(); 

gluPerspective(45.0f, 1.0f, 10.0f, 10000.0f); 

glMatrixMode(GL_MODELVIEW) ; 

glLoadIdentity(); 

gluLookAt(cameraPos[®], cameraPos[1], cameraPos[2], 
Q.0f, O.O0f, O.Of, O.Of, 1.0f, 0.0Ff); 
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// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT) ; 


if (animating) 

{ 
RegenerateSphere(); 
SetRenderingMethod(); 


// Draw objects in the scene 
DrawModels() ; 


// Flush drawing commands 
glutSwapBuffers() ; 


glutPostRedisplay(); 
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Two things to notice from this listing are the performance measurement code and the 
animation code. We need a way to test dynamically changing geometry, so when the 
animation toggle is on, we regenerate a new sphere vertex array for every frame. The 
random animated points sort of look like static. 


Because this chapter is all about squeezing more performance out of geometry processing, 
we would be remiss not to measure that performance in some way. For every 100 frames 
we render, we look at the time that has elapsed since we started those 100 frames. Divide 
the 100 frames across the elapsed time, and we have a rough count of frames per second. 
This number lets us compare vertex array performance against buffer object performance. 
It is printed to stdout, so look for it in the console window, not in the sample program’s 
graphics window. 


Migration to Buffer Objects 


Believe it or not, we’ve done the hard part. Generating or loading vertex array data still 
remains the same burden it always was. All we’re going to do differently now is tell 
OpenGL to store the vertex array data inside a buffer object. Same stuff, different wrapper. 


Before getting our hands dirty, we need to take care of one minor detail. Buffer objects are 
relatively new to OpenGL. The feature was first introduced as the 
GL_ARB_vertex_buffer_object extension and was promoted as a core feature quickly 
thereafter when OpenGL 1.5 was ratified. Some new features, such as depth textures and 
shadows, are easily integrated into applications because all they need are some new token 
definitions from a header file. Unfortunately, buffer objects need a bit more to make them 
start working. They introduce new API entrypoints that you need to latch onto before you 
can start using them. 


As you do with any feature, you must make sure the appropriate extension or version of 
OpenGL is available before trying to use it. Here, we’re checking for either OpenGL 1.5, 
which includes buffer objects, or for the extension that also provides the equivalent func- 
tionality: 


// Make sure required functionality is available! 

version = glGetString(GL_VERSION) ; 

if ((version[@] == '1') && (version[{1] == '.') && 
(version[2] >= '5') && (version[2] <= '9')) 


glVersion15 = GL_TRUE; 


if (!glVersion15 && !gltIsExtSupported("GL_ARB_vertex_buffer_object") ) 
{ 


Migration to Buffer Objects 


fprintf(stderr, "Neither OpenGL 1.5 nor GL_ARB_vertex_buffer_object" 
“extension is available!\n"); 

Sleep (2000) ; 

exit(Q); 


Now that we know the feature is supported, we need the function pointers for its entry- 
points. On Windows platforms, the function wglGetProcAddress queries for the function 
pointers based on a string containing the entrypoint name. Other platforms have other 
means of providing these pointers, so we’ve abstracted them into a tool library function, 
gltGetExtensionPointer. Note that if only the extension is available, the function names 
have the ARB suffix. If OpenGL 1.5 is available, we don’t need the suffix: 


// Load the function pointers 
if (glVersion15) 


{ 
glBindBuffer = gltGetExtensionPointer("glBindBuffer") ; 
glBufferData = gltGetExtensionPointer("glBufferData") ; 
glBufferSubData = gltGetExtensionPointer("“glBufferSubData") ; 
glDeleteBuffers = gltGetExtensionPointer("glDeleteBuffers") ; 
glGenBuffers = gltGetExtensionPointer("glGenBuffers") ; 
glMapBuffer = gltGetExtensionPointer("“glMapBuffer") ; 
glUnmapBuffer = gltGetExtensionPointer("glUnmapBuffer") ; 

} 

else 

{ 
glBindBuffer = gltGetExtensionPointer("glBindBufferARB" ) ; 
glBufferData = gltGetExtensionPointer("glBufferDataARB" ) ; 
glBufferSubData = gltGetExtensionPointer("glBufferSubDataARB") ; 
glDeleteBuffers = gltGetExtensionPointer("glDeleteBuffersARB" ) ; 
glGenBuffers = gltGetExtensionPointer("glGenBuffersARB" ) ; 
glMapBuffer = gltGetExtensionPointer("glMapBufferARB" ) ; 
glUnmapBuffer = gltGetExtensionPointer("glUnmapBufferARB") ; 

} 

if (!glBindBuffer || !glBufferData |} !glDeleteBuffers |} 
!glGenBuffers |; !glMapBuffer |; !glUnmapBuffer) 

{ 
fprintf(stderr, "Not all entrypoints were available!\n"); 
Sleep (2000) ; 
exit(Q); 
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Buffer Object Management 

Buffer objects are treated similarly to other objects in OpenGL, such as texture objects. 
They are created and their state initialized when first bound with the g1BindBuffer 
command. glGenBuffers can be called first to get a list of available names, but this 
command doesn’t actually create the buffer objects. You still need to bind the object name 
before it’s created. 


When you're finished with your buffer objects, you delete them with g1DeleteBuffers. If 
a deleted buffer is currently bound, that binding is undone, and the null buffer object 
(name zero) is implicitly bound, telling OpenGL to go back to using traditional (nonbuffer 
object) vertex arrays: 


// Generate a buffer object 
glGenBuffers(1, &bufferID) ; 


glBindBuffer(GL_ARRAY_BUFFER, bufferID) ; 


glDeleteBuffers(1, &bufferID) ; 


Rendering with Buffer Objects 

When you have a buffer object bound, it tells OpenGL to source its vertex array data from 
the buffer object’s data store instead of the vertex array pointers set via commands like 
glVertexPointer. But those pointers still are used. Instead of being pointers to data in 
client memory, when a buffer object is bound, these pointers are interpreted as offsets 
within the buffer object’s data store. 


In our buffer object program, the data used for both the vertex position array and the 
normal array begins right at the beginning of the buffer object’s data store, so an offset of 
zero is used. Our data is tightly packed without any padding or interlacing, so the stride 
parameter is also zero: 


glBindBuffer(GL_ARRAY_BUFFER, bufferID) ; 
// No stride, no offset 
glNormalPointer(GL_FLOAT, @, 0); 
glVertexPointer(3, GL_FLOAT, 0, 0); 


glDrawArrays(GL_POINTS, @, numSphereVertices) ; 


Loading Data into Buffer Objects 


We've described how to create buffer objects and how to tell OpenGL to use them as the 
source for rendering geometry. But we’re still missing one important piece of the puzzle: 
how to load data into the buffer object. A buffer object starts out its life with an empty 
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data store, so we need to take care of that before doing anything useful with them. The 
next two sections describe your two choices for loading up your buffer object’s data store. 


Copying Data into the Buffer Object 


The first option for loading your buffer object’s data store is analogous to the one you use 
for loading texture image data into a texture object. You give glTexImage a pointer to your 
texel data, and OpenGL copies it into its internal texture storage. If you give it a null 
pointer, g1TexImage still creates the texture with the size you want but leaves the texels 
uninitialized. If you want to respecify a portion of the texture, you can call glTexSubImage 
and tell it where and how much data to replace. 


The procedure is the same with buffer objects. You can call g1BufferData to establish the 
size of your data store and to supply a hint about how it will be accessed. Data is copied 
from the pointer you provide, unless the pointer is null, in which case the data remains 
uninitialized. g1BufferSubData can be called to respecify a portion of the data store. 


glTexImage and glTexSubImage entrypoints accept a target parameter to indicate which 
texture target is being specified, such as GL_TEXTURE_2D or GL_TEXTURE_SD. Similarly, 
glBufferData, glBufferSubData, and other buffer object entrypoints also accept a target 
parameter. This target reflects which type of buffer object is being operated on, and can 
either be GL_ARRAY_BUFFER or GL_ELEMENT_ARRAY_BUFFER. The former is used to store vertex 
array data, including colors, normals, texture coordinates, and positions. The latter is used 
to store array indices as used by g1DrawElements. 


In our sample program, if we’re not animating, we simply create the data store by calling 
glBufferData, providing a usage hint that the data will be static. All buffer sizes are 
measured in terms of “basic machine units,” or bytes: 


glBufferData(GL_ARRAY BUFFER, sizeof(GLfloat) * 
numSphereVertices * 3, sphereVertexArray, 
GL_STATIC_DRAW) ; 


However, if we are animating, we don’t want to incur the expense of re-creating the data 
store during every frame of animation, when in fact the size of the data remains the same. 
Instead, we’ll create the data store once when entering animation mode, with a null 
pointer so no data is copied yet, and providing a usage hint that the data will be stream- 
ing (used only once). Then, for each frame, we update the data with g1BufferSubData: 


// Establish streaming buffer object 

// Data will be loaded with subsequent calls to glBufferSubData 

glBufferData(GL_ARRAY_BUFFER, sizeof(GLfloat) * 
numSphereVertices * 3, NULL, GL_STREAM_DRAW) ; 


glBufferSubData(GL_ARRAY_BUFFER, @, sizeof(GLfloat) * 
numSphereVertices * 3, sphereVertexArray) ; 
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The usage hints that we’ve been passing into g1BufferData are really just that—hints. One 
OpenGL implementation may ignore them completely, whereas another implementation 
may be able to base crucial decisions on a hint that will greatly impact the performance of 
your buffer objects. If your data never changes, the driver may decide to put the data in 
local video memory. If you hint that your data is dynamic, the driver may place your data 
somewhere it is cheaper to constantly update it, such as AGP memory. Table 16.1 shows 
your three hint options. 


TABLE 16.1 Buffer Object Usage Hints 
Usage Hint Description 


GL_DYNAMIC_DRAW The data stored in the buffer object is likely to change frequently but is likely to 
be used as a source for drawing several times in between changes. This hint tells 
the implementation to put the data somewhere it won’t be too painful to 
update once in a while. 

GL_STATIC_DRAW The data stored in the buffer object is unlikely to change and will be used possi- 
bly many times as a source for drawing. This hint tells the implementation to 
put the data somewhere it’s quick to draw from, but probably not quick to 
update. 

GL_STREAM_DRAW The data store in the buffer object is likely to change frequently and will be used 
only once (or at least very few times) in between changes. This hint tells the 
implementation that you have time-sensitive data such as animated geometry 
that will be used once and then replaced. It is crucial that the data be placed 
somewhere quick to update, even at the expense of faster rendering. 


Note that there are actually READ and COPY variants of these hints in addition to the DRAW 
variants, but they are just in place for future use by extensions that build on buffer object 
functionality. Drawing from buffer object data is currently the only usage model available. 


Mapping the Buffer Object Directly 


This indirect copy method for loading buffer objects works well and follows similar para- 
digms already used by texture objects. However, after we set up our data in client memory, 
this method requires OpenGL to perform a copy into the buffer object memory. What if 
we could cut out the middleman and generate our geometry data right into the buffer 
object memory? 


We can. This procedure is called mapping your buffer object. By calling glMapBuffer, you 
can get a pointer to the buffer object’s data store mapped into the client’s address space. 
This means you can write to it, read from it, whatever you want. The only string attached 
is that you can’t use this memory as a source or destination parameter for other OpenGL 
entrypoints, such as glTexImage, glLightfv, gl1DrawPixels, and glReadPixels. Here we 
map the buffer object: 


Loading Data into Buffer Objects 


glBindBuffer(GL_ARRAY_BUFFER, bufferID); 


// Avoid pipeline flush during glMapBuffer by 
// marking buffer object's data store as empty 
glBufferData(GL_ARRAY_BUFFER, sizeof(GLfloat) * 
numSphereVertices * 3, NULL, 
animating ? GL_STREAM_DRAW : GL_STATIC_DRAW); 


sphereVertexArray = (GLfloat *)glMapBuffer(GL_ARRAY_BUFFER, 
GL_WRITE_ONLY) ; 


Before calling g1MapBuffer, we first call g1BufferData with a null pointer. We do this even 
if we’ve already created the buffer object because it helps prevent a performance degrada- 
tion during mapping. If there is any rendering still in the pipeline using old data in the 
buffer object, g1MapBuffer has to wait for the pipeline to flush out before it can return the 
mapped buffer pointer to the application. (Otherwise, the application might alter data 
that still needs to be used by previous drawing commands, corrupting that rendering.) 
Emptying the buffer object’s data store with the null pointer tells OpenGL that any data 
previously loaded into the buffer object is no longer needed. Mapping will then issue a 
new unused data store, avoiding the implicit pipeline synchronization that would other- 
wise occur. 


When calling glMapBuffer, you must provide an access flag that tells OpenGL in which 
ways you'll be accessing the buffer object’s data store while it’s mapped. Table 16.2 
describes the three access modes. 


TABLE 16.2 Mapped Buffer Object Access Modes 
Access Mode Description 


GL_READ_ONLY If you don’t need to change data but simply need to look at or copy data 
from the data store, you should use read-only mode. An implementation will 
attempt to map the data store in a way that is most efficient to read. 
Attempts to write to the mapped data store will likely be slow or cause your 
application to crash. 

GL_READ_WRITE If you must both read and write from the data, this is the mode you want to 
use, This mapping may be the least efficient because the implementation may 
have to compromise between mapping the data store in a way that is efficient 
to read versus efficient to write. 

GL_WRITE_ONLY If you don’t need to read back your data, just change it, you should use write- 
only mode. An implementation will attempt to map the data store in a way 
that is most efficient to write. Attempts to read from the data store will likely 
be slow or cause your application to crash. 
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You can’t start drawing from the buffer object until it has been unmapped again with the 
glUnmapBuffer command. This command lets OpenGL know that you’ve made your 
changes to the data, and you’re ready to hand control of the data store back to OpenGL. 
But things can go wrong during the time you have the buffer object mapped. Various 
system events, such as video mode changes or power-saving suspend/hibernation, can put 
your buffer object into a state where its integrity is unknown. The memory could have 
been temporarily reclaimed or powered off, leaving its contents corrupted or otherwise 
unknown. In this rare case, g1UnmapBuffer returns GL_FALSE, meaning that the application 
is responsible for resupplying all the data. This is an unavoidable burden if you want your 
application to be robust. In our program, all we have to do is call back into the generation 
routine to try again: 


if (!glUnmapBuffer(GL_ARRAY_BUFFER) ) 


{ 
// Some window system event has trashed our data... 
// Try, try again! 
RegenerateSphere() ; 

} 


Figure 16.4 shows the output from Listing 16.2. The output looks the same from both the 
traditional vertex array code and the buffer object code. But if you look at the frames per 
second output, that’s where you'll see the difference. Roughly a 25% to 200% improve- 
ment or more may be observed in mapped buffer object mode, depending on your 
OpenGL implementation and the number of vertices you’re throwing at it. 


3 Buffer Object Demo 


FIGURE 16.4 The 3x3x3 array of particle cloud spheres is a mini color cube. 


Loading Data into Buffer Objects 


LISTING 16.2 Code for Regenerating and Loading Sphere Vertex Array Data 


// Called to regenerate points on the sphere 
void RegenerateSphere(void) 


{ 


GLint i; 


if (mapBufferObject && useBufferObject) 
{ 
// Delete old vertex array memory 
if (sphereVertexArray) 
free(sphereVertexArray) ; 


glBindBuffer(GL_ARRAY_BUFFER, bufferID) ; 


// Avoid pipeline flush during glMapBuffer by 
// marking buffer object's data store as empty 
glBufferData(GL_ARRAY_BUFFER, sizeof(GLfloat) * 
numSphereVertices * 3, NULL, 
animating ? GL_STREAM_DRAW : GL_STATIC_DRAW); 


sphereVertexArray = (GLfloat *)glMapBuffer(GL_ARRAY_BUFFER, 
GL_WRITE_ONLY) ; 
} 
else if (!sphereVertexArray) 
{ 
// We need our old vertex array memory back 
sphereVertexArray = (GLfloat *)malloc(sizeof(GLfloat) * 
numSphereVertices * 3); 
if (!sphereVertexArray) 
{ 
fprintf(stderr, "Unable to allocate memory for vertex arrays!"); 
Sleep (2000) ; 
exit(Q); 


for (i = @; i < numSphereVertices; i++) 


{ 
GLfloat ri, r2, r38, scaleFactor; 


// pick a random vector 
r1 = (GLfloat)(rand() - (RAND _MAX/2)); 
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LISTING 16.2 Continued 


r2 = (GLfloat)(rand() - (RAND _MAX/2)); 
r3 = (GLfloat)(rand() - (RAND _MAX/2)); 


// determine normalizing scale factor 
scaleFactor = 1.0f / sqrt(ri*ri + r2*r2 + r3*r3); 


ri * scaleFactor; 
r2 * scaleFactor; 
r3 * scaleFactor; 


sphereVertexArray|[ (i*3)+0] 
sphereVertexArray[ (i*3)+1] 
sphereVertexArray[ (i*3)+2] 


} 
if (mapBufferObject && useBufferObject) 
{ 
if (!glUnmapBuffer(GL_ARRAY_BUFFER) ) 
{ 
// Some window system event has trashed our data... 
// Try, try again! 
RegenerateSphere(); 
} 
sphereVertexArray = NULL; 
} 


// Switch between buffer objects and plain old vertex arrays 
void SetRenderingMethod (void) 
{ 
if (useBufferObject) 
{ 
glBindBuffer(GL_ARRAY_BUFFER, bufferID) ; 
// No stride, no offset 
glNormalPointer(GL_FLOAT, 0, 0); 
glVertexPointer(3, GL_FLOAT, 0, 0); 


if (!mapBufferObject) 


{ 
if (animating) 
{ 
glBufferSubData(GL_ARRAY_BUFFER, @, sizeof(GLfloat) * 
numSphereVertices * 3, sphereVertexArray) ; 
} 
else 


A Few Loose Ends 


LISTING 16.2 Continued 


// If not animating, this gets called once 

// to establish new static buffer object 

glBufferData(GL_ARRAY_BUFFER, sizeof(GLfloat) * 
numSphereVertices * 3, sphereVertexArray, 
GL_STATIC_DRAW) ; 


} 
} 
} 
else 
{ 
glBindBuffer(GL_ARRAY_BUFFER, 0); 
glNormalPointer(GL_FLOAT, ®, sphereVertexArray) ; 
glVertexPointer(3, GL_FLOAT, 0, sphereVertexArray) ; 
} 


A Few Loose Ends 


The sample program did not touch upon a couple of things; thus, they have not been 
discussed yet. The first is state queries. As with all OpenGL state, the new state related to 
buffer objects can be queried. See the reference section for details, but here’s a brief break- 
down of the state-querying entrypoints introduced for buffer objects: 


¢ glGetBufferParameteriv—Query a buffer object’s usage hint, mapped access flag, 
mapped status, and size. 


¢ glGetBufferPointerv—Query a buffer object’s mapped address. 
¢ glGetBufferSubData—Query data from a buffer object’s data store. 


¢ glIsBuffer—Query if a buffer object name corresponds to an existing buffer object. 


Our sample also did not use array indices. The benefit of using g1DrawElements is that it 
removes redundancy from a pool of vertices. If a particular vertex is used more than once 
(for example, on a corner shared by several triangles), the vertex need only be present and 
processed once in the vertex array, but can be referenced many times in the array indices. 
Our spheres were composed of thousands of individual points, each used only once per 
sphere. So there was no benefit to be gained from array indices. However, should you use 
them in your application, it’s good to know that they can also be placed in buffer objects. 
You just need to use the GL_ELEMENT_ARRAY_BUFFER target instead of GL_ARRAY_BUFFER. 
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Summary 


OpenGL implementations have traditionally been crippled in terms of their ability to effi- 
ciently take geometry from an application and render it. This has not been due to any 
technical obstacle. The application had no way of telling the driver how large a data set 
would be used or how often it would be updated—crucial information for the driver to 
know where it should store the data. The problem has just been a lack of communication, 
cleared up by the introduction of buffer objects. 


Buffer objects are created and deleted just like texture objects. In fact, there’s a way to 
copy data into buffer objects that is also similar to texture objects. But buffer objects also 
provide a powerful mechanism for mapping buffer object memory to the application’s 
address space so the data store can be updated directly without an additional copy 
required. 


Reference 


g|BindBuffer 


Purpose: Binds a buffer object. 

Include File: <glext.h> 

Syntax: 

void glBindBuffer(GLenum target, GLuint buffer) ; 


Description: This function binds a buffer object to the vertex array or array index 
buffer target. If the buffer object has not been bound before, it’s created. 
Subsequent changes to or queries of the target will affect or return state 
from the bound buffer object. 


Parameters: 

target GLenum: The type of data that will be sourced from the buffer object. It 
can be one of the following constants: 
GL_ARRAY_BUFFER: The buffer object will store vertex array data. 
GL_ELEMENT_ARRAY_BUFFER: The buffer object will store array indices. 

buffer GLuint: The name of the buffer object to bind. 

Returns: None. 


See Also: glGenBuffers, glDeleteBuffers, glIsBuffer 


glBufferData 


Purpose: 
Include File: 
Syntax: 


Reference 


Creates and initializes a buffer object’s data store. 
<glext.h> 


void glBufferData(GLenum target, GLsizeiptr size, const GLvoid *data, GLenum usage); 


Description: 


Parameters: 
target 


size 
data 


usage 


This function creates and initializes a buffer object’s data store based on 
the specified size and performance hint. Any pre-existing data is deleted. 
If the data pointer is non-null, data is copied into the data store. If the 
buffer object’s data store is mapped, it becomes unmapped. 


GLenum: The buffer object target whose data store is being created. It can 
be one of the following constants: 

GL_ARRAY_BUFFER: The vertex array buffer object’s data store is being 
created. 

GL_ELEMENT_ARRAY_BUFFER: The array index buffer object’s data store is 
being created. 

GLsizeiptr: The size of the buffer object’s new data store, measured in 
basic machine units. 

const GLvoid *: The pointer to data that will be copied into the data 
store for initialization, or NULL if no data is to be copied. 

GLenum: A performance hint indicating how the data store will be 
accessed. It can be one of the following constants: 

GL_DYNAMIC_COPY: The data will be changed often and will be used for 
both reading from and writing to OpenGL. (Currently, there is no mecha- 
nism for reading from OpenGL.) 

GL_DYNAMIC_DRAW: The data will be changed often and will be used for 
writing to OpenGL. 

GL_DYNAMIC_READ: The data will be changed often and will be used for 
reading from OpenGL. (Currently, there is no mechanism for reading 
from OpenGL.) 

GL_STATIC_COPY: The data will be changed rarely and will be used for 
both reading from and writing to OpenGL. (Currently, there is no mecha- 
nism for reading from OpenGL.) 

GL_STATIC_DRAW: The data will be changed rarely and will be used for 
writing to OpenGL. 

GL_STATIC_READ: The data will be changed rarely and will be used for 
reading from OpenGL. (Currently, there is no mechanism for reading 
from OpenGL.) 
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GL_STREAM_COPY: The data will be accessed only once or a few times, and 
will be used for both reading from and writing to OpenGL. (Currently, 
there is no mechanism for reading from OpenGL.) 

GL_STREAM_DRAW: The data will be accessed only once or a few times, and 
will be used for writing to OpenGL. 

GL_STREAM_READ: The data will be accessed only once or a few times, and 
will be used for reading from OpenGL. (Currently, there is no mechanism 
for reading from OpenGL.) 


Returns: None. 

See Also: glBindBuffer, glBufferSubData, glMapBuffer, glUnmapBuffer 
glBufferSubData 

Purpose: Updates a subset of a buffer object’s data store. 

Include File: <glext.h> 

Syntax: 


void glBuffer SubData(GLenum target, GLintptr offset, GLsizeiptr size, 
const GLvoid *data); 


Description: 


Parameters: 
target 


offset 
size 
data 


Returns: 
See Also: 


This function replaces a portion of a buffer object's data store based on 
the specified size and offset into the data store. Data store contents 
outside of this portion remain unchanged. An error is generated if the 
buffer object's data store is currently mapped, or if any part of the speci- 
fied portion falls outside of the buffer object's data store. 


GLenum: The buffer object target whose data store is being updated. It can 
be one of the following constants: 


GL_ARRAY_BUFFER: The vertex array buffer object’s data store is being 
updated. 


GL_ELEMENT_ARRAY_BUFFER: The array index buffer object’s data store is 
being updated. 


GLintptr: The offset into the buffer object’s data store where data 
replacement begins, measured in basic machine units. 


GLsizeiptr: The size of the data store region being replaced, measured in 
basic machine units. 


const GLvoid *: The pointer to data that will be copied into the data 
store for initialization, or NULL if no data is to be copied. 


None. 
glBindBuffer, glBufferData, glMapBuffer, glUnmapBuf fer 


Reference 


glDeleteBuffers 

Purpose: Deletes one or more buffer objects. 
Include File: <glext.h> 

Syntax: 


void glDeleteBuffers(GLsizei n, const GLuint *buffers); 


Description: This function deletes buffer objects. The contents are deleted, and the 
names are marked as unused. If such a buffer object is currently bound in 
the current context, all such bindings are reset to zero. If an unused 
buffer object name or name zero is specified for deletion, that name is 


silently ignored. 
Parameters: 
n GLsizei: The number of buffer objects to delete. 
buffers const GLuint *: Pointer to an array containing the names of the buffer 
objects to delete. 
Returns: None. 
See Also: glGenBuffers, glBindBuffer, glIsBuffer 
glGenBuffers 
Purpose: Returns unused buffer object names. 
Include File: <glext.h> 
Syntax: 


void glGenBuffers(GLsizei n, GLuint *buffers) ; 


Description: This function returns unused buffer object names. The names can subse- 
quently be bound and created with g1BindBuffer. 

Parameters: 

n GLsizei: The number of buffer object names to return. 

buffers GLuint *: Pointer to an array to fill with unused buffer object names. 

Returns: None. 

See Also: glBindBuffer, glDeleteBuffers, glIsBuffer 


glGetBufferParameteriv 


Purpose: Queries properties of a buffer object. 
Include File: <glext.h> 
Syntax: 


void glGetBufferParameteriv(GLenum target, GLenum value, GLint *data); 
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Description: 


Parameters: 
target 


value 


data 


Returns: 
See Also: 


Buffer Objects: It’s Your Video Memory; You Manage It! 


This function queries the state of a currently bound buffer object. 


GLenum: The buffer object target whose state is being queried. It can be 
one of the following constants: 
GL_ARRAY_BUFFER: The vertex array buffer object’s state is being queried. 


GL_ELEMENT_ARRAY_BUFFER: The array index buffer object’s state is being 
queried. 

GLenum: The buffer object state being queried. It can be one of the follow- 
ing constants: 

GL_BUFFER_ACCESS: The buffer object’s access flag, which can be one of 
the following: GL_READ_ONLY, GL_WRITE_ONLY, or GL_READ_WRITE. 
GL_BUFFER_MAPPED: The flag indicating whether the buffer object is 
currently mapped. 

GL_BUFFER_SIZE: The size of the buffer object, measured in basic machine 
units. 

GL_BUFFER_USAGE: The buffer object’s usage pattern, which can be one of 
the following: GL_DYNAMIC_COPY, GL_DYNAMIC_READ, GL_DYNAMIC_WRITE, 
GL_STATIC_COPY, GL_STATIC_READ, GL_STATIC_WRITE, GL_STREAM_COPY, 
GL_STREAM_READ, or GL_STREAM_WRITE. 

GLint *: A pointer to the location where the query results are to be 
written. 

None. 


glBindBuffer, glBufferData, glMapBuffer, glUnmapBuffer 


glGetBufferPointerv 


Purpose: 
Include File: 
Syntax: 


Queries the pointer to a mapped buffer object’s data store. 
<glext.h> 


void glGetBufferPointerv(GLenum target, GLenum pname, GLvoid **params) ; 


Description: 


Parameters: 
target 


This function returns the pointer to which the buffer object’s data store is 
mapped. If the buffer object is not currently mapped, NULL is returned. 
Depending on the implementation, NULL may also be returned if queried 
by a client that did not map the buffer object. 


GLenum: The buffer object target whose data store pointer is being queried. 
It can be one of the following constants: 


Reference 


GL_ARRAY_BUFFER: The vertex array buffer object’s pointer is being 
queried. 


GL_ELEMENT_ARRAY_BUFFER: The array index buffer object’s pointer is 
being queried. 


pname GLenum: The pointer being queried, which must be the constant 
BUFFER_MAP_POINTER. 

params GLvoid **: A pointer to the location where the query result will be 
stored. 

Returns: None. 

See Also: glBindBuffer, glMapBuffer 

glGetBufferSubData 

Purpose: Queries a subset of a buffer object’s data store. 

Include File: <glext.h> 

Syntax: 


void glGetBuffer SubData(GLenum target, GLintptr offset, GLsizeiptr size, 
GLvoid *data); 


Description: This function returns data from the specified portion of the current 
buffer object’s data store. An error is generated if the buffer object is 
currently mapped. 


Parameters: 

target GLenum: The buffer object target whose data is being queried. It can be 
one of the following constants: 
GL_ARRAY_BUFFER: The vertex array buffer object’s data is being queried. 
GL_ELEMENT_ARRAY_BUFFER: The array index buffer object’s data is being 
queried. 

offset GLintptr: The offset into the buffer object’s data store where data query- 
ing begins, measured in basic machine units. 

size GLsizeiptr: The size of the data store region being queried, measured in 
basic machine units. 

data GLvoid *: A pointer to the location where queried data is returned. 

Returns: None. 

See Also: glBindBuffer, glBufferData, gl1BufferSubData, glMapBuffer, 


glUnmapBuf fer 
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gllsBuffer 

Purpose: Queries whether a name is a buffer object name. 
Include File: <glext.h> 

Syntax: 


GLboolean glIsBuffer(GLuint buffer) ; 


Description: This function queries whether the specified name is the name of a buffer 
object. 

Parameters: 

buffer GLuint: The buffer object name to be queried. 

Returns: GLboolean: GL_TRUE is returned if a buffer object with this name has 
previously been bound and not yet deleted. Otherwise, GL_FALSE is 
returned. 

See Also: glBindBuffer, glDeleteBuffers, glGenBuffers 

glMapBuffer 

Purpose: Maps a buffer object’s data store. 

Include File: <glext.h> 

Syntax: 


GLvoid *glMapBuffer(GLenum target, GLenum access) ; 


Description: This function maps a buffer object’s data store to the client’s address 
space. The data can then be directly read and/or written relative to the 
returned pointer, depending on the specified buffer access flag. An error 
is generated if the buffer object’s data store is already mapped. The para- 
meter values passed to OpenGL commands may not be sourced from the 
returned pointer. 


Parameters: 
target GLenum: The buffer object target whose data store is being mapped. It can 
be one of the following constants: 


GL_ARRAY_BUFFER: The vertex array buffer object’s data store is being 
mapped. 
GL_ELEMENT_ARRAY_BUFFER: The array index buffer object’s data store is 
being mapped. 

access GLenum: The access flag dictating whether it is possible to read from, write 
to, or both read from and write to the mapped buffer object’s data store. 
It can be one of the following constants: 
GL_READ_ONLY: Restricts access to the buffer object’s data store such that 
writes to the data store may not be performed. 


Reference 


GL_READ_WRITE: Allows reads from and writes to the buffer object’s data 
store without restriction. 


GL_WRITE_ONLY: Restricts access to the buffer object’s data store such that 
reads from the data store may not be performed. 


Returns: GLvoid *: A pointer to the buffer object’s data store mapped to the 
client’s address space. 

See Also: glBindBuffer, glBufferData, glBufferSubData, glUnmapBuffer 

glUnmapBuffer 

Purpose: Unmaps a buffer object’s data store. 


Include File: 
Syntax: 


<glext.h> 


GLboolean glUnmapBuffer(GLenum target) ; 


Description: 


Parameters: 
target 


Returns: 


See Also: 


This function unmaps a buffer object’s data store. A data store must be 
unmapped before it can once again be accessed by OpenGL. An error is 
generated if the buffer object’s data store is not currently mapped. 


GLenum: The buffer object target whose data store is being unmapped. It 
can be one of the following constants: 

GL_ARRAY_BUFFER: The vertex array buffer object’s data store is being 
unmapped. 

GL_ELEMENT_ARRAY_BUFFER: The array index buffer object’s data store is 
being unmapped. 

GLboolean: GL_TRUE is returned unless some platform-dependent event 
has occurred, such as a video mode or power-saving mode change. Such 
events may leave the buffer object’s data store in an undefined state, in 
which case GL_FALSE is returned, and the client must repopulate the data 
store. 


glBindBuffer, glMapBuffer 
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CHAPTER 17 


Occlusion Queries: Why Do More 
Work Than You Need To? 


by Benjamin Lipchak 
WHAT YOU'LL LEARN IN THIS CHAPTER: 
How To Functions You'll Use 
Create and delete query objects glGenQueries/glDeleteQueries 
Define bounding box occlusion queries glBeginQuery/glEndQuery 
Retrieve the results from an occlusion query glGetQuery0bjectiv 


Complex scenes contain hundreds of objects and thousands upon thousands of polygons. 
Consider the room you’re in now, reading this book. Look at all the furniture, objects, 
other people or pets and think of the rendering power needed to accurately represent their 
complexity. Several readers will find themselves happily sitting on a crate near a computer 
in an empty studio apartment, but the rest will envision a significant rendering workload 
around them. 


Now think of all the things you can’t see: objects hidden behind other objects, in drawers, 
or even in the next room. From most viewpoints, these objects are invisible to the viewer. 
If you rendered the scene, the objects would be drawn, but eventually something would 
draw over the top of them. Why bother doing all that work for nothing? 


Enter occlusion queries. In this chapter, we describe a powerful new feature included in 
OpenGL 1.5 that can save a tremendous amount of vertex processing and texturing at the 
expense of a bit of extra nontextured fill rate. Often this trade-off is a very favorable one. 
We explore the use of occlusion detection and witness the dramatic increase in frame rates 
this technique affords. 


892 


CHAPTER 17. Occlusion Queries: Why Do More Work Than You Need To? 


The World Before Occlusion Queries 


To show off the improved performance possible through the use of occlusion queries, we 
need an experimental control group. We’ll draw a scene without any fancy occlusion 
detection. The scene is contrived so that there are plenty of objects both visible and 
hidden at any given time. 


First, we’ll draw the “main occluder.” An occluder is a large object in a scene that tends to 
occlude, or hide, other objects in the scene. An occluder is often low detail, whereas the 
objects it occludes may be much higher in detail. Good examples are walls, floors, and 
ceilings. The main occluder in this scene is a grid made out of six walls, as illustrated in 
Figure 17.1. Listing 17.1 shows how the walls are actually just scaled cubes. 


Occlusion Query Demo 


FIGURE 17.1. Our main occluder is a grid constructed out of six walls. 


LISTING 1 7.1. Main Occluder with Six Scaled and Translated Solid Cubes 


// Called to draw the occluding grid 
void DrawOccluder (void) 
{ 


glColor3f(0.5f, 0.25f, 0.O0f); 


glPushMatrix() ; 
glScalef(30.0f, 30.0f, 1.0f); 
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LISTING 17.1. Continued 


glTranslatef(0.0f, 0.0f, 50.0f); 
glutSolidCube(10.0f) ; 
glTranslatef(0.0f, @.0f, -100.0f); 
glutSolidCube(10.0f) ; 
glPopMatrix(); 


glPushMatrix(); 

glScalef(1.0f, 30.0f, 30.0f); 
glTranslatef(50.0f, 0.0f, 0.0f); 
glutSolidCube(10.0f) ; 
glTranslatef(-100.0f, 0.0f, 0.0f); 
glutSolidCube(10.0f) ; 
glPopMatrix(); 


glPushMatrix(); 

glScalef(30.0f, 1.0f, 30.0f); 
glTranslatef(0.0f, 50.0f, 0.0f); 
glutSolidCube(10.0f) ; 
glTranslatef(Q.0f, -100.0f, 0.0f); 
glutSolidCube(10.0f) ; 
glPopMatrix(); 


In each grid compartment, we’re going to put a highly tessellated textured sphere. These 
spheres are our “occludees,” objects possibly hidden by the occluder. We need the high 
vertex count and texturing to accentuate the rendering burden so that we can subse- 
quently relieve that burden courtesy of occlusion queries. Just as we did in the preceding 
chapter where we were showing off our buffer objects, we need to lay on the vertices! 
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Figure 17.2 shows the picture resulting from Listing 17.2. If you find this workload too 
heavy, feel free to reduce the tessellation in glutSolidSphere from the 100s to smaller 
numbers. Or if your OpenGL implementation is still hungry for more, go ahead and 
increase the tessellation. 


LISTING 17.2 Drawing 27 Highly Tessellated Spheres in a Color Cube 


// Called to draw sphere 
void DrawSphere(GLint sphereNum) 
{ 


glutSolidSphere(50.0f, 100, 100); 
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LISTING 17.2 Continued 


} 
void DrawModels(void) 
{ 
// Turn on texturing just for spheres 
glEnable(GL_TEXTURE_2D) ; 
glEnable(GL_TEXTURE_GEN_S) ; 
glEnable(GL_TEXTURE_GEN_T); 
// Draw 27 spheres in a color cube 
for (rf = Oj r-< dy r++) 
{ 
for (g = @; g < 3; gtt) 
{ 
for (b = 0; b < 3; b+t) 
{ 
glColor3f(r * 0.5f, g * O@.5f, b * 0.5f); 
glPushMatrix(); 
glTranslatef(100.0f * r - 100.0f, 
100.0f * g - 100.0f, 
100.0f * b - 100.0f); 
DrawSphere((r*9)+(g*3) +b); 
glPopMatrix(); 
} 
} 
} 
glDisable(GL_TEXTURE_2D) ; 
glDisable(GL_TEXTURE_GEN_S) ; 
glDisable(GL_TEXTURE_GEN_T) ; 
} 


Listing 17.2 marks the completion of our picture. If we were happy with the rendering 
performance, we could end the chapter right here. But if the sphere tessellation is cranked 
up high enough, or if you were to introduce complex multitexturing or fragment shading 
to the sphere rendering, frame rates should be unacceptable. So read on! 


Bounding Boxes 


3 Occlusion Query Demo 


FIGURE 17.2 Twenty-seven high-detail spheres will act as our occludees. 


Bounding Boxes 


The theory behind occlusion detection is that if an object’s bounding volume is not visible, 
neither is the object. A bounding volume is any volume that completely contains the 
object. The whole point of occlusion detection is to cheaply draw a simple bounding 
volume to find out whether you can avoid drawing the actual complex object. So the 
more complex our bounding volume is, the more it negates the purpose of the optimiza- 
tion we’re trying to create. 


The simplest bounding volume is a cube, also called a bounding box. Eight vertices, six 
faces. You can easily create a bounding box for any object just by scanning for its 
minimum and maximum coordinates on each of the x-, y-, and z-axes. For our spheres 
with a 50-unit radius, a bounding box with sides of length 100 units will fit perfectly. 


Be aware of the trade-off when using such a simple and arbitrary bounding volume. The 
bounding volume may have very few vertices, but it will touch many more pixels than the 
original object would have. With a few additional strategically placed vertices, you can 
turn your bounding box into a more useful shape and significantly reduce the fill rate 
overhead. Fortunately, the bounding box is drawn without any fancy texturing or shading, 
so its overall fill rate cost will often be less than the original object anyway. Figure 17.3 
shows an example of how different bounding volume shapes affect pixel count and vertex 
count. 
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Bounding volume 
KK 
UV) 
NV 
Nom box octahedron dodecahedron —_icosahedron 
# faces 4 6 8 12 20 
# vertices 4 8 6 20 12 
% of pixels overkill 136% 120% 81% 58% 34% 


FIGURE 17.3 Various bounding volumes with their pros and cons. 


When we draw our bounding volumes, we’re going to enable an occlusion query that will 
count the number of fragments that pass the depth test (and the stencil test if enabled). 
Therefore, we don’t care how the bounding volumes look. In fact, we don’t even need to 
draw them to the screen at all. So we'll shut off all the bells and whistles before rendering 
the bounding volume, including writes to the color buffer: 


glShadeModel (GL_FLAT) ; 
glDisable(GL_LIGHTING) ; 
glDisable(GL_COLOR_MATERIAL) ; 
glDisable(GL_NORMALIZE) ; 

// Texturing is already disabled 


glColorMask(0, 0, 0, 0); 


After all this talk about occlusion queries, we’re finally going to create some. But first, we 
need to come up with names for them. Here, we request 27 names, one for each sphere’s 
query, and we provide a pointer to the array where the new names should be stored: 


// Generate occlusion query names 
glGenQueries(27, queryIDs) ; 


When we're done with them, we delete the query objects, indicating there are 27 names 
to be deleted in the provided array: 


glDeleteQueries(27, queryIDs) ; 


Occlusion query objects are not bound like other OpenGL objects, such as texture objects 
and buffer objects. Instead, they’re created by calling g1BeginQuery. This marks the begin- 
ning of our query. The query object has an internal counter that keeps track of the 
number of fragments that would make it to the framebuffer—if we hadn’t shut off the 
color buffer’s write mask. Beginning the query resets this counter to zero to start a fresh 


query. 


Bounding Boxes 


Then we draw our bounding volume. The query object’s internal counter is incremented 
every time a fragment passes the depth test, and thus is not hidden by our main occluder, 
the grid which we've already drawn. For some algorithms, it’s useful to know exactly how 
many fragments were drawn, but for our purposes here, all we care about is whether the 
counter is zero or nonzero. This value corresponds to whether any part of the bounding 
volume is visible or if all fragments were discarded by the depth test. 


When we’re finished drawing our bounding volume, we mark the end of our query by 
calling glEndQuery. This tells OpenGL we’re done with this query and lets us continue 
with another query or ask for the result back. Because we’re drawing 27 spheres, we can 
improve the performance by using 27 different query objects. This way, we can queue up 
the drawing of all 27 bounding volumes without disrupting the pipeline by reading back 
the query results in between. 


Listing 17.3 illustrates the rendering of our bounding volumes, bracketed by the beginning 
and ending of our query. Then we proceed to redraw the main occluder and possibly draw 
the actual spheres. Notice the code for visualizing the bounding volume whereby we leave 
the color buffer’s write mask enabled. This way, we can see and compare the different 
bounding volume shapes. 


LISTING 17.3 Beginning the Query, Drawing the Bounding Volume, Ending the Query, Then 
Moving on to Redraw the Actual Scene 


// Called to draw scene objects 
void DrawModels(void) 


{ 
GLint r, g, b; 


if (occlusionDetection {| showBoundingVolume) 

{ 
// Draw bounding boxes after drawing the main occluder 
DrawOccluder(); 


// All we care about for bounding box is resulting depth values 
glShadeModel(GL_FLAT) ; 
glDisable(GL_LIGHTING) ; 
glDisable(GL_COLOR_MATERIAL) ; 
g1Disable(GL_NORMALIZE) ; 
// Texturing is already disabled 
if (!showBoundingVolume) 
glColorMask(0, @, @, 0); 


// Draw 27 spheres in a color cube 
for (Pr = 0) f < 35, rtt) 


{ 
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LISTING 17.3 Continued 
for (g = 0; g < 3; g++) 


{ 


for (b = 0; b < 3; b++) 


{ 


if (showBoundingVolume) 
glColor3f(r * @.5f, g * 0.5f, b * 0.5f); 


glPushMatrix(); 
glTranslatef(100.0f * r - 100.0f, 

100.0f * g - 100.0f, 

100.0f * b - 100.0f); 
glBeginQuery(GL_SAMPLES PASSED, queryIDs[(r*9)+(g*3)+b]) ; 
switch (boundingVolume) 


{ 
case Q: 
glutSolidCube(100.0f) ; 
break; 
case 1: 
glScalef(150.0f, 150.0f, 150.0f); 
glutSolidTetrahedron() ; 
break; 
case 2: 
glScalef(90.0f, 90.0f, 90.0f); 
glutSolidOctahedron(); 
break; 
case 3: 
glScalef(40.0f, 40.0f, 40.0f); 
glutSolidDodecahedron() ; 
break; 
case 4: 
glScalef(65.0f, 65.0f, 65.0f); 
glutSolidIcosahedron() ; 
break; 
} 
glEndQuery(GL_SAMPLES_ PASSED) ; 
glPopMatrix(); 


if (!showBoundingVolume) 
glClear(GL_DEPTH_BUFFER_BIT) ; 
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LISTING 17.3 Continued 


// Restore normal drawing state 
glShadeModel(GL_SMOOTH) ; 
glEnable(GL_LIGHTING) ; 
glEnable(GL_COLOR_MATERIAL) ; 
glEnable(GL_NORMALIZE) ; 
glColorMask(1, 1, 1, 1); 


DrawOccluder(); 


// Turn on texturing just for spheres 
glEnable(GL_TEXTURE_2D) ; 
glEnable(GL_TEXTURE_GEN_S) ; 
glEnable(GL_TEXTURE_GEN_T); 


// Draw 27 spheres in a color cube 
for (r = 0; r < 3; r++) 


{ 
for (g = 0; g < 3; g++) 
{ 
for (b = @; b < 3; b++) 
{ 
glColor3f(r * @.5f, g * 0.5f, b * @.5f); 
glPushMatrix(); = 
glTranslatef(100.0f * r - 100.0f, N 
100.0f * g - 100.0f, 
100.0f * b - 100.0f); 
DrawSphere((r*9)+(g*3)+b) ; 
glPopMatrix(); 
} 
} 
} 


glDisable(GL_TEXTURE_2D) ; 
glDisable(GL_TEXTURE_GEN_S); 
glDisable(GL_TEXTURE_GEN_T); 


DrawSphere contains the magic where we decide whether to actually draw the sphere. Our 
query results are waiting for us inside our 27 query objects. Let’s find out which are 
hidden and which we have to draw. 
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Querying the Query Object 
The moment of truth is here. The jury is back with its verdict. We want to draw as little as 


possible, so we’re hoping each and every one of our queries resulted in no fragments being 
touched. But if you think about this grid of spheres, you know that’s not going to happen. 


No matter what angle we’re looking at our grid, unless we zoom way in, there will always 
be at least 9 spheres in view. Worst case is you'll see all the spheres on three faces of our 
grid: 19 spheres. Still, in that worst case, we save ourselves from drawing 8 spheres. That’s 
almost a 30% savings in per-vertex costs. Best case, we save 66%, skipping 18 spheres. If 
we zoom in on one sphere, we could conceivably avoid drawing 26 spheres! 


So how do you determine your luck? You simply query the query object. That sounds 
confusing, but this is a regular old query for OpenGL state. It just happens to be from 
something called a query object. In Listing 17.4, we call g1GetQueryObjectiv to see whether 
the pass counter is zero, in which case we won’t draw the sphere. 


LISTING 17.4 Checking the Query Results and Drawing the Sphere Only If We Have To 


// Called to draw sphere 
void DrawSphere(GLint sphereNum) 


{ 
GLboolean occluded = GL_FALSE; 
if (occlusionDetection) 
{ 
GLint passingSamples; 
// Check if this sphere would be occluded 
glGetQueryObjectiv(queryIDs[sphereNum] , GL_QUERY_RESULT, 
&passingSamples) ; 
if (passingSamples == 0) 
occluded = GL_TRUE; 
} 
if (!occluded) 
{ 
glutSolidSphere(50.0f, 100, 100); 
} 
} 


That’s all there is to it. Each sphere’s query is checked in turn, and we decide whether to 
draw the sphere. We’ve included a mode where we can disable the occlusion detection to 
see how badly our performance suffers. Depending on how many spheres are visible, you 
may see a boost of two times or more thanks to occlusion detection. 


Querying the Query Object 


In addition to the query result, you can also query to find out whether the result is imme- 
diately available. If we didn’t render the 27 bounding volumes back to back, and instead 
asked for each result immediately, the bounding box rendering might still have been in 
the pipeline and the result may not have been ready yet. You can query 
GL_QUERY_RESULT_AVAILABLE to find out whether the result is ready. If it’s not, querying 
GL_QUERY_RESULT will stall until the result is available. So instead of stalling, you could 
find something useful for your application to do while you wait for the results to be ready. 
In our case, we planned ahead to do a bunch of work in between to be certain our first 
query result would be ready by the time we finished our 27th query. 


Other state queries include the currently active query name (which query is in the middle 
of a g1BeginQuery/glEndQuery, if any) and the number of bits in the implementation’s 
pass counter. An implementation is allowed to advertise a 0-bit counter, in which case 
occlusion queries are useless and shouldn’t be used. In Listing 17.5, we check for that case 
during an application’s initialization right after checking for extension strings and entry- 
points. 


LISTING 17.5 Ensuring Occlusion Queries Are Truly Supported 


// Make sure required functionality is available! 

version = glGetString(GL_VERSION) ; 

if ((version[®] == '1') && (version[1] == '.') && 
(version[2] >= '5') && (version[2] <= '9')) 


glVersion15 = GL_TRUE; 


if (!glVersion15 && !gltIsExtSupported("GL_ARB_occlusion_query") ) 
{ 
fprintf(stderr, "Neither OpenGL 1.5 nor GL_ARB occlusion_query" 
"extension is available!\n"); 
Sleep (2000) ; 
exit(Q); 


// Load the function pointers 

if (glVersion15) 

{ 
glBeginQuery = gltGetExtensionPointer("“glBeginQuery") ; 
glDeleteQueries = gltGetExtensionPointer("glDeleteQueries") ; 
glEndQuery = gltGetExtensionPointer("glEndQuery") ; 
glGenQueries = gltGetExtensionPointer("glGenQueries") ; 
glGetQueryiv = gltGetExtensionPointer("glGetQueryiv") ; 
glGetQueryObjectiv = gltGetExtensionPointer("glGetQueryObjectiv") ; 
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LISTING 17.5 Continued 


glGetQueryObjectuiv = gltGetExtensionPointer("glGetQueryObjectuiv") ; 
glIsQuery = gltGetExtensionPointer("glIsQuery") ; 


} 

else 

{ 
glBeginQuery = gltGetExtensionPointer("glBeginQueryARB") ; 
glDeleteQueries = gltGetExtensionPointer("glDeleteQueriesARB") ; 
glEndQuery = gltGetExtensionPointer("glEndQueryARB") ; 
glGenQueries = gltGetExtensionPointer("glGenQueriesARB" ) ; 
glGetQueryiv = gltGetExtensionPointer("glGetQueryivARB") ; 
glGetQueryObjectiv = gltGetExtensionPointer("glGetQuery0bjectivARB") ; 
glGetQueryObjectuiv = gltGetExtensionPointer("glGetQueryObjectuivARB" ) ; 
glIsQuery = gltGetExtensionPointer("glIsQueryARB") ; 

} 


if (!glBeginQuery |} !glDeleteQueries |} !glEndQuery || !glGenQueries || 
!glGetQueryiv |}; !glGetQueryObjectiv || !glGetQueryObjectuiv |} 


!glIsQuery) 
{ 
fprintf(stderr, "Not all entrypoints were available!\n"); 
Sleep (2000) ; 
exit(0); 
} 


// Make sure query counter bits is non-zero 
glGetQueryiv(GL_SAMPLES_PASSED, GL_QUERY_COUNTER_BITS, &queryCounterBits) ; 
if (queryCounterBits == Q) 


{ 
fprintf(stderr, "Occlusion queries not really supported!\n"); 
fprintf(stderr, “Available query counter bits: @\n"); 
Sleep (2000) ; 
exit(); 
} 


The only other query to be aware of is glIsQuery. This command just checks whether the 
specified name is the name of an existing query object, in which case it returns GL_TRUE. 
Otherwise, it returns GL_FALSE. 


Reference 


Summary 


When rendering complex scenes, sometimes we waste hardware resources by rendering 
objects that will never be seen. We can try to avoid the extra work by testing whether an 
object will show up in the final image. By drawing a bounding box, or some other simple 
bounding volume, around the object, we can cheaply approximate the object in the scene. 
If occluders in the scene hide the bounding box, they would also hide the actual object. 
By wrapping the bounding box rendering with a query, we can count the number of pixels 
that would be hit. If the bounding box hits no pixels, we can guarantee that the original 
object would also not be drawn, so we can skip rendering it. Performance improvements 
can be dramatic, depending on the complexity of the objects in the scene and how often 
they are occluded. 


Reference 


glBeginQuery 

Purpose: Marks the beginning of an occlusion query. 
Include File: <glext.h> 

Syntax: 

void glBeginQuery(GLenum target, GLuint id); 


Description: This function starts an occlusion query with the specified name by reset- 
ting its samples-passed counter to zero. If the query object does not yet 
exist, it is created. An error is thrown if a query is already in progress or if 
the specified query object name is zero. 


Parameters: 

target GLenum: The type of query object being restarted. Must be 
GL_SAMPLES_PASSED. 

id GLuint: The name of the query object being restarted. 

Returns: None. 

See Also: glEndQuery, glGenQueries, glDeleteQueries, glIsQuery 

glDeleteQueries 

Purpose: Deletes one or more query objects. 

Include File: <glext.h> 

Syntax: 


void glDeleteQueries(GLsizei n, const GLuint *ids); 
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Description: This function deletes query objects. The contents are deleted, and the 
names are marked as unused. If an unused query object name or name 
zero is specified for deletion, that name is silently ignored. 


Parameters: 

n GLsizei: The number of query objects to delete. 

ids const GLuint *: Pointer to an array containing the names of the query 
objects to delete. 

Returns: None. 

See Also: glBeginQuery, glEndQuery, glGenQueries, glIsQuery 

glEndQuery 

Purpose: Marks the end of an occlusion query. 


Include File: <glext.h> 
Syntax: 
void glEndQuery(GLenum target) ; 


Description: This function marks the end of the current occlusion query. If no occlu- 
sion query is in progress, an error is thrown. 

Parameters: 

target GLenum: The type of query object being ended. Must be 
GL_SAMPLES_PASSED. 

Returns: None. 

See Also: glBeginQuery, glDeleteQueries, glQueryObjectiv, 
glGetQueryObjectuiv 

glGenQueries 

Purpose: Returns unused query object names. 


Include File: <glext.h> 
Syntax: 


void glGenQueries(GLsizei n, const GLuint *ids); 


Description: This function returns unused query object names. The query objects can 
subsequently be created and started with g1BeginQuery. 


Parameters: 

n GLsizei: The number of query object names to return. 

ids GLuint *: Pointer to an array to fill with unused query object names. 
Returns: None. 


See Also: glDeleteQueries, glBeginQuery, gllsQuery 


Reference 


glGetQueryiv 

Purpose: Queries properties of a query object target. 
Include File: <glext.h> 

Syntax: 

void glGetQueryiv(GLenum target, GLenum pname, GLint *params); 


Description: This function queries the state of the specified query object target. This is 
state not specific to a particular query object, but rather shared by all 
query objects. 


Parameters: 

target GLenum: The type of query object being queried. Must be 
GL_SAMPLES_PASSED. 

pname GLenum: The query object target state being queried. It can be one of the 
following constants: 
GL_CURRENT_QUERY: The name of the currently active occlusion query 
object. If no occlusion query object is active, zero is returned. 
GL_QUERY_COUNTER_BITS: The implementation-dependent number of bits 
in the counter used to accumulate passing samples. 

params GLint *: A pointer to the location where the query results are written. 

Returns: None. 

See Also: glGetQueryObjectiv, glGetQueryObjectuiv, glIsQuery 

glGetQueryObject 

Purpose: Queries properties of a query object. 

Include File: <glext.h> 

Syntax: 


void glGetQueryObjectiv(GLuint id, GLenum pname, GLint *params); 
void glGetQueryObjectuiv(GLuint id, GLenum pname, GLuint *params); 


Description: This function queries the state of the query object with the specified 
name. If the name does not correspond to an existing query object, or if 
the query object is currently active (inside a g1BeginQuery/glEndQuery), 
an error is thrown. 


Parameters: 
id GLuint: The query object name whose state is being queried. 
pname GLenum: The query object state being queried. It can be one of the follow- 


ing constants: 
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params 


Returns: 
See Also: 


gllsQuery 
Purpose: 
Include File: 
Syntax: 


GL_QUERY_RESULT: Indicates the value of the query object’s passed samples 
counter. 


GL_QUERY_RESULT_AVAILABLE: Indicates whether the above result is imme- 
diately available. If a delay would occur waiting for the query result, 
GL_FALSE is returned. Otherwise, GL_TRUE is returned, which also indi- 
cates that the results of all previous queries are available as well. 


GLint */GLuint *: A pointer to the location where the query results are 
written. 


None. 
glBeginQuery, glEndQuery, glGetQueryiv, glIsQuery 


Queries whether a name is a query object name. 
<glext.h> 


GLboolean glIsQuery(GLuint id); 


Description: 
Parameters: 
id 

Returns: 


See Also: 


This function queries whether the specified name is the name of a query 
object. 


GLuint: The query object name to be queried. 


GLboolean: GL_TRUE is returned if a query object with this name has 
previously been created (with glBeginQuery) and not yet deleted. 
Otherwise, GL_FALSE is returned. 


glBeginQuery, glEndQuery, glGenQueries, glDeleteQueries 


CHAPTER 18 
Depth Textures and Shadows 


by Benjamin Lipchak 
WHAT YOU’LL LEARN IN THIS CHAPTER: 
How To Functions You'll Use 
Draw your scene from the light’s perspective gluLookAt /gluPerspective 
Copy texels from the depth buffer into a depth texture glCopyTexImage2D 
Use eye linear texture coordinate generation glTexGen 
Set up shadow comparison glTexParameter 


Shadows are an important visual cue, both in reality and in rendered scenes. At a very 
basic level, shadows give us information about the location of objects in relation to each 
other and to light sources, even if the light sources are not visible in the scene. When it 
comes to games, shadows can make an already immersive environment downright spooky. 
Imagine turning the corner in a torch-lit dungeon and stepping into the shadow of your 
worst nightmare. Peter Pan had it easy. 


In Chapter 5, “Color, Materials, and Lighting: The Basics,” we described a low-tech way of 
projecting an object onto a flat plane, in effect “squishing” it to appear as a shadow. 
Another technique utilizing the stencil buffer, known as shadow volumes, has been widely 
used, but it tends to require significant pre-processing of geometry and high fill rates to 
the stencil buffer. In OpenGL 1.4, a more elegant approach to shadow generation has been 
made possible: shadow mapping. 


The theory behind shadow mapping is simple. What parts of your scene would fall in 
shadow? Answer: The parts that light doesn’t directly hit. Think of yourself in the light’s 
position in your virtual scene. What would the light see if it were the camera? Everything 
the light sees would be lit. Everything else falls in shadow. Figure 18.1 will help you visu- 
alize the difference between the camera’s viewpoint and the light’s viewpoint. 
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FIGURE 18.1 The camera and the light have different perspectives on the scene. 


When the scene is rendered from the light’s perspective, the side effect is a depth buffer 
full of useful information. At every pixel in the resulting depth buffer, we know the rela- 
tive distance from the light to the nearest surface. These surfaces are lit by the light 
source. Every other surface farther away from the light source remains in shadow. 


What we'll do is take that depth buffer, copy it into a texture, and project it back on the 
scene, now rendered again from the normal camera angle. We'll use that projected texture 
to automatically determine what parts of what objects are in light, and which remain in 
shadow. Sounds easy, but each step of this technique requires careful attention. 


Be That Light 


Our first step is to draw the scene from the light’s perspective. We'll use several built-in 
GLUT objects to show off how well this technique works, even when casting shadows on 
nonplanar surfaces, such as other objects in the scene. You can change the viewpoint by 
manually setting the modelview matrix, but for this example, we use the gluLookAt helper 
function to facilitate the change: 


gluLookAt(lightPos[@], lightPos[1], lightPos[2], 
Q.0f, O.0f, O.0f, O.O0f, 1.0f, 0.0Ff); 


Be That Light 


Fit the Scene to the Window 


In addition to this modelview matrix, we also need to set up the projection matrix to 
maximize the scene’s size in the window. Even if the light is far away from the objects in 
the scene, to achieve the best utilization of the space in our shadow map, we would still 
like the scene to fill the available space. We’ll set up the near and far clipping planes based 
on the distance from the light to the nearest and farthest objects in the scene. Also, we'll 
estimate the field of view to contain the entire scene as closely as possible: 


// Save the depth precision for where it's useful 

lightToSceneDistance = sqrt(lightPos[0] * lightPos[0] + 
lightPos[1] * lightPos[1] + 
lightPos[2] * lightPos[2]); 

nearPlane = lightToSceneDistance - 150.0f; 

if (nearPlane < 50.0f) 

nearPlane = 50.0f; 
// Keep the scene filling the depth texture 
fieldOfView = 17000.0f / lightToSceneDistance; 


glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 
gluPerspective(fieldOfView, 1.0f, nearPlane, nearPlane + 300.0f); 


No Bells or Whistles, Please 

When we draw the first pass of the scene, the light’s viewpoint, we don’t actually want to 
see it. We just want to tap into the resulting depth buffer. So we'll draw to the back buffer 
and never bother swapping. We can further accelerate this pass by masking writes to the 
color buffer. And because all we care about is the depth values, we obviously don’t care 
about lighting, smooth shading, or anything else that isn’t going to affect the result. Shut 
it all off. All we need to specify is the raw geometry: 


glShadeModel (GL_FLAT) ; 
glDisable(GL_LIGHTING) ; 
glDisable(GL_COLOR_MATERIAL) ; 
glDisable(GL_NORMALIZE) ; 
glColorMask(0, 0, 0, 0); 


The output from Listing 18.1 is not visible, but Figure 18.2 illustrates via grayscale what 
the depth buffer contains. 


909 


SL 


910 CHAPTER 18 Depth Textures and Shadows 


FIGURE 18.2 If we could see the depth buffer, this is what it would look like. 


LISTING 18.1 Rendering the Light’s Viewpoint into the Shadow Map 


// Called to draw scene objects 
void DrawModels(void) 


{ 


// Draw plane that the objects rest on 
glColor3f(0.0f, 0.0f, ®.90f); // Blue 
glNormal3f(Q@.0f, 1.0f, 0.0f); 
glBegin(GL_QUADS) ; 
glVertex3f(-100.0f, -25.0f, -100.0f); 
glVertex3f(-100.0f, -25.0f, 100.0f); 
glVertex3f(100.0f, -25.0f, 100.0f); 
glVertex3f(100.0f, -25.0f, -100.0f); 
glEnd(); 


// Draw red cube 
glColor3f(1.0f, 0.0f, 0.O0f); 
glutSolidCube(48.0f) ; 


// Draw green sphere 
glColor3f(0.0f, 1.0f, 0.0f); 
glPushMatrix() ; 
glTranslatef(-60.0f, 0.0f, 0.0f); 
glutSolidSphere(25.0f, 50, 50); 
glPopMatrix(); 


LISTING 18.1 Continued 


Be That Light 


// Draw yellow cone 

glColor3f(1.0f, 1.0f, 0.0f); 
glPushMatrix(); 

glRotatef(-90.0f, 1.0f, @.0f, 0.0f); 
glTranslatef(60.0f, 0.0f, -24.0f); 
glutSolidCone(25.0f, 50.0f, 50, 50); 
glPopMatrix(); 


// Draw magenta torus 
glColor3f(1.0f, @.0f, 1.0f); 
glPushMatrix(); 

glTranslatef(0.0f, 0.0f, 60.0f); 
glutSolidTorus(8.0f, 16.0f, 50, 50); 
glPopMatrix(); 


// Draw cyan octahedron 
glColor3f(0.0f, 1.0f, 1.0f); 
glPushMatrix(); 
glTranslatef(Q.0f, 0.0f, -60.0f); 
glScalef(25.0f, 25.0f, 25.0f); 
glutSolidOctahedron() ; 
glPopMatrix(); 


// Called to regenerate the shadow map 
void RegenerateShadowMap (void) 


{ 


GLfloat lightToSceneDistance, nearPlane, fieldOfView; 
GLfloat lightModelview[16], lightProjection[16]; 


// Save the depth precision for where it's useful 

lightToSceneDistance = sqrt(lightPos[®] * lightPos[0] + 
lightPos[1] * lightPos[1] + 
lightPos[2] * lightPos[2]); 

nearPlane = lightToSceneDistance - 150.0f; 

if (nearPlane < 50.0f) 

nearPlane = 50.0f; 
// Keep the scene filling the depth texture 
fieldOfView = 17000.0f / lightToSceneDistance; 


glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 
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LISTING 18.1 Continued 


gluPerspective(fieldOfView, 1.0f, nearPlane, nearPlane + 300.0f) ; 
glGetFloatv(GL_PROJECTION MATRIX, lightProjection) ; 
// Switch to light's point of view 
glMatrixMode(GL_MODELVIEW) ; 
glLoadiIdentity(); 
gluLookAt(lightPos[®], lightPos[1], lightPos[2], 
Q.0f, O.O0f, 0.0f, O.0f, 1.0f, 0.0f); 
glGetFloatv(GL_MODELVIEW_MATRIX, lightModelview) ; 
glViewport(®, @, shadowSize, shadowSize) ; 


// Clear the depth buffer only 
glClear(GL_DEPTH_BUFFER_BIT) ; 


// All we care about here is resulting depth values 
glShadeModel (GL_FLAT) ; 

glDisable(GL_LIGHTING) ; 
glDisable(GL_COLOR_MATERIAL) ; 
glDisable(GL_NORMALIZE) ; 

glColorMask(0, @, @, 0); 


// Overcome imprecision 
glEnable(GL_POLYGON_OFFSET_FILL) ; 


// Draw objects in the scene 
DrawModels(); 


// Copy depth values into depth texture 
glCopyTexImage2D(GL_TEXTURE_2D, ®, GL_DEPTH_COMPONENT, 
@, @, shadowSize, shadowSize, Q); 


// Restore normal drawing state 
glShadeModel(GL_SMOOTH) ; 
glEnable(GL_LIGHTING) ; 
glEnable(GL_COLOR_MATERIAL) ; 
glEnable(GL_NORMALIZE) ; 
glColorMask(1, 1, 1, 1); 
glDisable(GL_POLYGON_OFFSET_FILL) ; 


// Set up texture matrix for shadow map projection 
glMatrixMode(GL_TEXTURE) ; 
glLoadidentity(); 
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LISTING 18.1 Continued 


glTranslatef(0.5f, @.5f, @.5f); 
glScalef(@.5f, 0.5f, 0.5f); 

glMultMatrixf (lightProjection) ; 
glMultMatrixf (lightModelview) ; 


A New Kind of Texture 


We want to copy the depth values from the depth buffer into a texture for use as the 
shadow map. OpenGL allows you to copy color values directly into textures via 
glCopyTexImage2D. Until OpenGL 1.4, this capability was possible only for color values. 
But now depth textures are available. 


Depth textures simply add a new type of texture data. We’ve had base formats with red, 
green, and blue color data and/or alpha, luminosity, or intensity. To this list, we now add 
a depth base format. The internal formats that can be requested include 
GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, and GL_DEPTH_COMPONENTS2, each reflect- 
ing the number of bits per texel. Typically, you’ll want a format that matches the precision 
of your depth buffer. OpenGL makes it easy by letting you use the generic 
GL_DEPTH_COMPONENT internal format that usually adopts whichever specific format 
matches your depth buffer. 


After drawing the light’s view into the depth buffer, we want to copy that data directly 
into a depth texture. This saves us the trouble of using both glReadPixels and 
glTexImage2D: 


glCopyTexImage2D(GL_TEXTURE_2D, @, GL_DEPTH_COMPONENT, 
@, ®@, shadowSize, shadowSize, 0); 


Note that Listing 18.1, for drawing the light’s view and regenerating the shadow map, 
needs to be executed only when objects in the scene move or the light source moves. If 
the only thing moving is the camera angle, you can keep using the same depth texture. 
Remember, when only the camera moves, the light’s view of the scene isn’t affected. (The 
camera is invisible.) We can reuse the existing shadow map in this case. 


SL 


Draw the Shadows First?! 


Yes, we will draw the shadows first. But, you ask, if a shadow is defined as the lack of light, 
why do we need to draw shadows at all? Strictly speaking, you don’t need to draw them if 
you have a single spotlight. If you leave the shadows black, you'll achieve a stark effect 
that may suit your purposes well. But if you don’t want pitch black shadows and still want 
to make out details inside the shadowed regions, you’ll need to simulate some ambient 
lighting in your scene: 
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GLfloat lowAmbient[4] 
GLfloat lowDiffuse[4] 


{0.1f, O.1f, O.1f, 1.0f}; 
{0.35f, 0.35f, 0.35f, 1.0f}; 


glLightfv(GL_LIGHT®, GL_AMBIENT, lowAmbient) ; 
glLightfv(GL_LIGHT®, GL_DIFFUSE, lowDiffuse); 


// Draw objects in the scene 
DrawModels(); 


We've added a bit of diffuse lighting as well to help convey shape information. If you use 
only ambient lighting, you end up with ambiguously shaped solid-colored regions. Figure 
18.3 shows the scene so far, entirely in shadow. 


[3 Shadow Mapping Demo 


FIGURE 18.3 The entire scene is in shadow before the lit areas are drawn. 


Some OpenGL implementations support an extension, GL_ARB_shadow_ambient, which 
makes this first shadow drawing pass unnecessary. In this case, both the shadowed regions 
and the lit regions are drawn simultaneously. More on that optimization later. 


And Then There Was Light 


Right now, we just have a very dimly lit scene. To make shadows, we need some brightly 
lit areas to contrast the existing dimly lit areas, turning them into shadows. But how do 


And Then There Was Light 


we determine which areas to light? This is key to the shadow mapping technique. After 
we've decided where to draw, we’ll draw brighter simply by using greater lighting coeffi- 
cients, twice as bright as the shadowed areas: 


GLfloat ambientLight[] = { 0.2f, 0.2f, 0.2f, 1.0f}; 
GLfloat diffuseLight[] = { 0.7f, 0.7f, 0.7f, 1.0f}; 


glLightfv(GL_LIGHT@, GL_AMBIENT, ambientLight); 
glLightfv(GL_LIGHT®, GL_DIFFUSE, diffuseLight); 


Projecting Your Shadow Map: The “Why” 


Remember that texture matrix code from Listing 18.1? Now’s the time to explain it. The 
goal here is to project the shadow map (the light’s viewpoint) of the scene back onto the 
scene as if emitted from the light, but viewed from the camera’s position. We’re projecting 
those depth values, which represent the distance from the light to the first object hit by 
the light’s rays. Reorienting the texture coordinates into the right coordinate space is 
going to take a bit of math. If you care only about the “how” and not the “why,” you can 
safely skip over this section. 


In Chapter 4, “Geometric Transformations: The Pipeline,” we explained the process of 
transforming vertices from object space to eye space, then to clip space, on to normalized 
device coordinates, and finally to window space. We have two different sets of matrices in 
play performing these transformations: one for the light view and the other for the regular 
camera view. Figure 18.4 shows the two sets of transformations in use. 


*MViight Light's “Pht 


y” eye space 


World space 
\ *WVcomera Comera’s | *Poomerg | Camera's |__y 
eye space dlip space 


FIGURE 18.4 The large arrow in the center shows the transformations we need to apply to 
our eye linear texture coordinates. 
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Any texture projection usually begins with eye linear texture coordinate generation. This 
process will automatically generate our texture coordinates. Unlike object linear texture 
coordinate generation, the eye linear coordinates aren’t tied to the geometry. Instead, it’s 
as if there is a film projector casting the texture onto the scene. But it doesn’t just project 
onto flat surfaces like a movie screen. Think about what happens when you walk in front 
of projector. The movie is projected on your irregularly shaped body. The same thing 
happens here. 


We need to end up with texture coordinates that will index into our shadow map in the 
light’s clip space. We start off with our projected eye linear texture coordinates in the 
camera’s eye space. So we need to first backtrack to world space and then transform to the 
light’s eye space and finally to the light’s clip space. This transformation can be summa- 
rized by the following series of matrix multiplications: 


M = Pane” MV ase” MVenera 


But wait, there’s more. The light’s clip space doesn’t quite bring us home free. Remember 
that clip space is in the range [-1,1] for each of the x, y, and z coordinates. The shadow 
map depth texture, like all standard 2D textures, needs to be indexed in the range [0,1]. 
Also, the depth values against which we’re going to be comparing are in the range [0,1], so 
we'll also need our z texture coordinate in that range. A simple scale by one half (S) and 
bias by one half (B) will do the trick: 


M=B*S*P,.*MV,,. *MV...,” 


If you’re unfamiliar with OpenGL matrix notation, you’re probably asking why these 
matrices are in reverse order. After all, we need to apply the inverse of the camera’s 
modelview first, and the bias by one half translation is the last transformation we need. 
What's the deal? It’s really simple, actually. OpenGL applies a matrix (M) to a coordinate 
(T) in a seemingly backward way, too. So, you want to read everything right to left when 
thinking about the order of transformations being applied to your coordinate: 


T=M*T 
=B*S* Pt MV. * MV YT 


light camera 


This is standard representation. Nothing to see here. Move along. 


Projecting Your Shadow Map: The “How” 


We understand what matrix transformations need to be applied to our eye linear-gener- 
ated texture coordinate to have something useful to index into our shadow map texture. 
But how do we apply these transformations? 


And Then There Was Light 


Texture coordinates, like vertex positions, also are automatically subjected to matrix trans- 
formation. However, instead of both a modelview and a projection matrix, texture coordi- 
nates are multiplied by only a single texture matrix. There’s nothing special to enable; the 
texture matrix is always applied to every texture coordinate, whether automatically gener- 
ated or explicitly provided via immediate mode entrypoints, vertex arrays, and so on. You 
may not have known the texture matrix was at work because, by default, the identity 
matrix causes it to leave texture coordinates unchanged. 


We'll use this texture matrix in combination with texture coordinate generation to achieve 
the necessary texture coordinate manipulation. To set up the texture matrix, we’ll start 
with an identity matrix and multiply in each of our required transformations discussed in 
the preceding section: 


glGetFloatv(GL_PROJECTION MATRIX, lightProjection); 
glGetFloatv(GL_MODELVIEW MATRIX, lightModelview) ; 


// Set up texture matrix for shadow map projection 
glMatrixMode(GL_TEXTURE) ; 

glLoadIdentity(); 

glTranslatef(0.5f, @.5f, 0.5f); 

glScalef(@.5f, 0.5f, 0.5f); 
glMultMatrixf(lightProjection) ; 

glMultMatrixf (lightModelview) ; 


When setting our light’s projection and modelview matrices before drawing the light’s 
view, we conveniently queried and saved off these matrices so we could apply them later 
to the texture matrix. Our scale and bias operations to map [-1,1] to [0,1] are easily 
expressed as glScalef and glTranslatef calls. 


But where’s the multiplication by the inverse of the camera’s modelview matrix? Glad you 
asked. OpenGL anticipated the need for this transformation when using eye linear texture 
coordinate generation. A post-multiply by the inverse of the current modelview matrix is 
included in the eye plane equations. All you have to do is make sure your camera’s 
modelview is installed at the time you call gl1TexGenfv: 


glMatrixMode(GL_MODELVIEW) ; 

glLoadidentity(); 

gluLookAt(cameraPos[®], cameraPos[1], cameraPos[2], 
Q.0f, O.0f, O.0f, O.0f, 1.0f, 0.0f); 


{1.0f, 0.0f, 0.0f, 0.0f}; 
{0.0f, 1.0f, O0.0f, 0.0f}; 
{0.0f, O.0f, 1.0f, 0.0F}; 
{0.0f, 0.0f, O.0f, 1.0f}; 


GLfloat sPlane[4] 
GLfloat tPlane[4] 
GLfloat rPlane[4] 
GLfloat qPlane[4] 


" 


917 


SL 


918 


CHAPTER 18 Depth Textures and Shadows 


// Set up the eye plane for projecting the shadow map on the scene 
glEnable(GL_TEXTURE_GEN_S) ; 

glEnable(GL_TEXTURE_GEN_T); 

glEnable(GL_TEXTURE_GEN_R); 

glEnable(GL_TEXTURE_GEN_Q); 

glTexGenfv(GL_S, GL_EYE_PLANE, sPlane) ; 

glTexGenfv(GL_T, GL_EYE_PLANE, tPlane) ; 

glTexGenfv(GL_R, GL_EYE_PLANE, rPlane); 

glTexGenfv(GL_Q, GL_EYE_PLANE, qgPlane) ; 


glTexGeni(GL_S, GL_TEXTURE_GEN MODE, GL_EYE_LINEAR); 
glTexGeni(GL_T, GL_TEXTURE_GEN MODE, GL_EYE_LINEAR); 
glTexGeni(GL_R, GL_TEXTURE_GEN MODE, GL_EYE_LINEAR) ; 
glTexGeni(GL_Q, GL_TEXTURE_GEN MODE, GL_EYE_LINEAR); 


The Shadow Comparison 


We have rendered our light view and copied it into a shadow map. We have our texture 
coordinates for indexing into the projected shadow map. The scene is dimly lit, ready for 
the real lights. The moment is near for completing our scene. We just need to combine the 
ingredients. First, there’s some important state we can “set and forget” during initializa- 
tion: 


// Hidden surface removal 
glEnable(GL_DEPTH_TEST) ; 
glDepthFunc(GL_LEQUAL) ; 


// Set up some texture state that never changes 
glGenTextures(1, &shadowTextureID) ; 
glBindTexture(GL_TEXTURE_2D, shadowTexturelID) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP); 


We set the depth test to less than or equal so that we can draw the lit pass on top of the 
dim pass. Otherwise, because the geometry is identical, the lit pass would always fail the 
depth test, and nothing would show up after the dimly lit shadow pass. 


Then we generate and bind to our shadow map, which is the only texture used in this 
demo. We set our texture coordinate wrap modes to clamp. It makes no sense to repeat 
the projection. For example, if the light affects only a portion of the scene, but the camera 
is zoomed out to reveal other unlit parts of the scene, you don’t want your shadow map to 
be repeated infinitely across the scene. You want your texture coordinates clamped so that 
only the lit portion of the scene has the shadow map projected onto it. 


And Then There Was Light 


Depth textures contain only a single source component representing the depth value. But 
texture environments expect four components: red, green, blue, and alpha. OpenGL gives 
you the flexibility as to how you want the depth mapped. Choices for the depth texture 
mode include GL_ALPHA (0,0,0,D), GL_LUMINANCE (D,D,D,1), and GL_INTENSITY (D,D,D,D). 
We're going to need the depth broadcast to all four channels, so we choose the intensity 
mode: 


glTexParameteri(GL_TEXTURE_2D, GL_DEPTH_TEXTURE_MODE, GL_INTENSITY) ; 


Obviously, we need to enable texturing to put the shadow map into effect. We set the 
compare mode to GL_COMPARE_R_TO_TEXTURE. If we don’t set this, all we'll get is the depth 
value in the texture. But we want more than that. We want the depth value compared to 
our texture coordinate’s R component: 


// Set up shadow comparison 

glEnable(GL_TEXTURE_2D) ; 

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_COMPARE_MODE, 
GL_COMPARE_R_TO_TEXTURE) ; 


The R component of the texture coordinate represents the distance from the light source 
to an object’s surface. The shadow map’s depth value represents the distance from the 
light to the first surface it hits. By comparing one to the other, we can tell whether a 
surface was the first to be hit by a ray of light, or if that surface is farther away from the 
light, and hence is in the shadow cast by the first lit surface: 


D’=(R<=D)?1:0 


Other comparison functions are also available. In fact, OpenGL 1.5 enables you to use all 
the same relational operators that you can use for depth test comparisons. GL_LEQUAL is 
the default, so we don’t need to change it. 


Another two settings we need to consider are the minification and magnification filters. 
We're going to use point sampling: 


glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN FILTER, GL_NEAREST) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG FILTER, GL_NEAREST) ; 


However, some implementations may be able to smooth the edges of your shadows if you 
enable bilinear or trilinear filtering. On such an implementation, multiple comparisons are 
performed and the results are averaged. This is called percentage-closer filtering. 


Great. We have a bunch of Os and 1s. But we don’t want to draw black and white. Now 
what? Easy. We just need to set up a texture environment mode, GL_MODULATE, that multi- 
plies the Os and 1s by the incoming color resulting from lighting: 


glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE); 
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Finally, we’re done, right?! We have drawn our lit areas now. But wait. Where shadows 
appear, we just drew black over our previous ambient lighting pass. How do we preserve 
the ambient lighting for shadowed regions? Alpha testing will do the trick. We asked for 
intensity depth texture mode. Therefore, our Os and 1s are present in the alpha compo- 
nent as well as the color components. Using an alpha test, we can tell OpenGL to discard 
any fragments in which we didn’t get a 1: 


// Enable alpha test so that shadowed fragments are discarded 
glAlphaFunc(GL_GREATER, 0.9f); 
glEnable(GL_ALPHA_TEST) ; 


Okay. Now we're done. Figure 18.5 shows the output from Listing 18.2, shadows and all. 


3 Shadow Mapping Demo 


FIGURE 18.5 A brightly lit pass is added to the previous ambient shadow pass. 


LISTING 18.2 Drawing the Ambient Shadow and Lit Passes of the Scene 


// Called to draw scene 

void RenderScene( void) 

{ 
// Track camera angle 
glMatrixMode(GL_PROJECTION) ; 
glLoadIdentity(); 
gluPerspective(45.0f, 1.0f, 1.0f, 1000.0f); 
glMatrixMode(GL_MODELVIEW) ; 
glLoadIdentity(); 


And Then There Was Light 


LISTING 18.2 Continued 


gluLookAt(cameraPos[®], cameraPos[1], cameraPos[2], 


Q.0f, 0.0f, O.0f, O.0f, 1.0f, 0.0f); 


glViewport(®, ®, windowWidth, windowHeight) ; 


// Track light position 
glLightfv(GL_LIGHT®, GL_POSITION, lightPos); 


// Clear the window with current clearing color 
glClear(GL_COLOR_BUFFER_BIT ! GL_DEPTH BUFFER BIT); 


if (showShadowMap) 


{ 


// Display shadow map for educational purposes 
glMatrixMode(GL_PROJECTION) ; 
glLoadidentity(); 
glMatrixMode (GL_MODELVIEW) ; 
glLoadIdentity(); 
glMatrixMode (GL_TEXTURE) ; 
glPushMatrix(); 
glLoadidentity(); 
glEnable(GL_TEXTURE_2D) ; 
glDisable(GL_LIGHTING) ; 
glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_REPLACE) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_COMPARE_MODE, GL_NONE) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN FILTER, GL_LINEAR); 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR) ; 
// Show the shadowMap at its actual size relative to window 
g1Begin(GL_QUADS) ; 
glTexCoord2f(0.0f, 0.0f); 
glVertex2f(-1.0f, -1.0f); 
glTexCoord2f(1.0f, 0.0f); 
glVertex2f (((GLfloat) shadowSize/ (GLfloat)windowWidth) *2.0-1.0f, 
-1.0F); 
glTexCoord2f(1.0f, 1.0f); 
glVertex2f (((GLfloat) shadowSize/ (GLfloat)windowWidth)*2.0-1.0f, 
((GLfloat) shadowSize/ (GLfloat )windowHeight)*2.0-1.0f); 
glTexCoord2f(0.0f, 1.0f); 
glVertex2f(-1.0f, 
((GLfloat) shadowSize/ (GLfloat )windowHeight)*2.0-1.0f); 
glEnd(); 
glDisable(GL_TEXTURE_2D) ; 
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LISTING 18.2 Continued 


glEnable(GL_LIGHTING) ; 

glPopMatrix(); 

glMatrixMode(GL_PROJECTION) ; 
gluPerspective(45.0f, 1.0f, 1.0f, 1000.0f); 
glMatrixMode(GL_MODELVIEW) ; 


} 

else if (noShadows) 

{ 
// Set up some simple lighting 
glLightfv(GL_LIGHT®, GL_AMBIENT, ambientLight) ; 
glLightfv(GL_LIGHT®, GL_DIFFUSE, diffuseLight) ; 
// Draw objects in the scene 
DrawModels(); 

} 

else 

sf 


GLfloat sPlane[4] 
GLfloat tPlane[4] 
GLfloat rPlane[4] 
GLfloat qPlane[4] 


{1.0f, 0.0f, 0.0f, 0.0f}; 
{0.0f, 1.0f, 0.0f, 0.0f}; 
{0.0f, O.0f, 1.0f, 0.0f}; 
{0.0f, O.0f, 0.0f, 1.0f}; 


if (l!ambientShadowAvailable) 

{ 
GLfloat lowAmbient[4] = {0.1f, 0.1f, O.1f, 1.0f}; 
GLfloat lowDiffuse[4] = {@.35f, 0.35f, @.35f, 1.0f}; 


// Because there is no support for an “ambient" 
// shadow compare fail value, we'll have to 

// draw an ambient pass first... 
glLightfv(GL_LIGHT®, GL_AMBIENT, lowAmbient) ; 
glLightfv(GL_LIGHT@, GL_DIFFUSE, lowDiffuse) ; 


// Draw objects in the scene 
DrawModels() ; 


// Enable alpha test so that shadowed fragments are discarded 
glAlphaFunc(GL_GREATER, 0.9f); 
glEnable(GL_ALPHA_TEST) ; 
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LISTING 18.2 Continued 


glLightfv(GL_LIGHTO, GL_AMBIENT, ambientLight); 
glLightfv(GL_LIGHT®, GL_DIFFUSE, diffuseLight); 


// Set up shadow comparison 

glEnable(GL_TEXTURE_2D); 

glTexEnvi(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE) ; 

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_COMPARE_MODE, 
GL_COMPARE_R_TO TEXTURE) ; 

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST) ; 

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST) ; 


// Set up the eye plane for projecting the shadow map on the scene 
glEnable(GL_TEXTURE_GEN_S); 

glEnable(GL_TEXTURE_GEN_T) ; 

glEnable(GL_TEXTURE_GEN_R); 

glEnable(GL_TEXTURE_GEN_Q); 

glTexGenfv(GL_S, GL_EYE_PLANE, sPlane); 

glTexGenfv(GL_T, GL_EYE_PLANE, tPlane) ; 

glTexGenfv(GL_R, GL_EYE_PLANE, rPlane); 

glTexGenfv(GL_Q, GL_EYE_PLANE, qPlane); 


// Draw objects in the scene 
DrawModels(); 


glDisable(GL_ALPHA_TEST) ; 
glDisable(GL_TEXTURE_2D) ; 
glDisable(GL_TEXTURE_GEN_S) ; 
glDisable(GL_TEXTURE_GEN_T); 
glDisable(GL_TEXTURE_GEN_R); 
glDisable(GL_TEXTURE_GEN_Q) ; 


if (glGetError() != GL_NO_ERROR) 
fprintf(stderr, "GL Error!\n"); 


// Flush drawing commands 
glutSwapBuffers() ; 


// This function does any needed initialization on the rendering 
// context. 
void SetupRC() 
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LISTING 18.2 Continued 
{ 


const GLubyte *version; 
fprintf(stdout, "Shadow Mapping Demo\n\n"); 


// Make sure required functionality is available! 
version = glGetString(GL_VERSION) ; 


if (((version[®] != '1') |! (version[{1] != '.') |} 
(version[2] < '4') || (version[2] > '9')) && // 1.4+ 
(!gltIsExtSupported("GL_ARB_shadow") ) ) 
{ 
fprintf(stderr, "Neither OpenGL 1.4 nor GL_ARB_shadow" 
"extension is available!\n"); 
Sleep (2000) ; 
exit(Q); 
} 


// Check for optional extension 
if (gltIsExtSupported("GL_ARB_shadow_ambient") ) 


{ 
ambientShadowAvailable = GL_TRUE; 

} 

else 

{ 
fprintf(stderr, "GL_ARB_shadow_ambient extension not available!\n"); 
fprintf(stderr, “Extra ambient rendering pass will be required.\n\n"); 
Sleep (2000) ; 

} 


fprintf(stdout, "Controls:\n"); 

fprintf(stdout, "\tc\t\tControl camera movement\n") ; 
fprintf(stdout, "\tl\t\tControl light movement\n\n") ; 
fprintf(stdout, "\tx/X\t\tMove +/- in x direction\n"); 
fprintf(stdout, "\ty/Y\t\tMove +/- in y direction\n"); 
fprintf(stdout, "\tz/Z\t\tMove +/- in z direction\n\n"); 
fprintf(stdout, "\tf/F\t\tChange polygon offset factor +/-\n\n"); 
fprintf(stdout, "\ts\t\tToggle showing current shadow map\n"); 
fprintf(stdout, "\tn\t\tToggle showing scene without shadows\n\n"); 
fprintf(stdout, "\tq\t\tExit demo\n\n"); 


// Black background 
glClearColor(Q.0f, 0.0f, 0.0f, 1.0f ); 


Two Out of Three Ain’t Bad 


LISTING 18.2 Continued 


// Hidden surface removal 
glEnable(GL_DEPTH_TEST) ; 
glDepthFunc (GL_LEQUAL) ; 
glPolygonOffset(factor, 0.0f); 


// Set up some lighting state that never changes 
glShadeModel(GL_SMOOTH) ; 

glEnable(GL_LIGHTING) ; 
glEnable(GL_COLOR_MATERIAL) ; 
glEnable(GL_NORMALIZE) ; 

glEnable(GL_LIGHT®) ; 


// Set up some texture state that never changes 
glGenTextures(1, &shadowTexturelID) ; 
glBindTexture(GL_TEXTURE_2D, shadowTextureID) ; 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP); 
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP); 
glTexParameteri(GL_TEXTURE_2D, GL_DEPTH_TEXTURE_MODE, GL_INTENSITY) ; 
if (ambientShadowAvailable) 

glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_COMPARE_FAIL_VALUE_ARB, 

@.5f); 

glTexGeni(GL_S, GL_TEXTURE_GEN_MODE, GL_EYE_LINEAR) ; 
glTexGeni(GL_T, GL_TEXTURE_GEN MODE, GL_EYE_LINEAR); 
glTexGeni(GL_R, GL_TEXTURE_GEN_MODE, GL_EYE_LINEAR); 
glTexGeni(GL_Q, GL_TEXTURE_GEN_MODE, GL_EYE_LINEAR) ; 


RegenerateShadowMap() ; 


Two Out of Three Ain’t Bad 


In Listing 18.2, you’ll notice code hinging on the ambientShadowAvailable variable. The 
minimum requirement for the rest of this example is OpenGL 1.4 support, or at least 
support for the GL_ARB_shadow extension. If, however, your implementation supports the 
GL_ARB_shadow_ambient extension, you can cut down the amount of work significantly. 


Currently, we’ve described three rendering passes: one to draw the light’s perspective into 
the shadow map, one to draw the dimly lit ambient pass, and one to draw the shadow- 
compared lighting. Remember, the shadow map needs to be regenerated only when the 
light position or objects in the scene change. So sometimes there are three passes, and 
other times just two. With GL_ARB_shadow_ambient, we can eliminate the ambient pass 
entirely. 
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Instead of Os and 1s resulting from the shadow comparison, this extension allows us to 
replace another value for the 0s when the comparison fails. So if we set the fail value to a 
half, the shadowed regions are still halfway lit, the same amount of lighting we were 
previously achieving in our ambient pass: 


if (ambientShadowAvailable) 
glTexParameterf (GL_TEXTURE_2D, GL_TEXTURE_COMPARE_FAIL_VALUE_ARB, 
@.5f); 


This way, we also don’t need to enable the alpha test. 


A Few Words About Polygon Offset 


Even on a surface closest to the light source, you will always discover minor differences in 
the floating-point values associated with the R texture coordinate and the shadow map’s 
depth value. This can result in “self-shadowing,” whereby the imprecision leads to a 
surface shadowing itself. You can mitigate this problem by applying a depth offset when 
rendering into the shadow map: 


// Overcome imprecision 
glEnable(GL_POLYGON_OFFSET_FILL) ; 


glPolygonOffset(factor, 0.0f); 


While the depth offset will help guarantee that surfaces that shouldn’t be shadowed won't 
be, it also artificially shifts the position of shadows. A balance needs to be struck when it 
comes to polygon offset usage. Figure 18.6 illustrates what you'll see if you don’t use 
enough depth offset. 
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FIGURE 18.6 Shadow comparison imprecision looks a lot like depth buffer “Z-fighting.” 


Summary 


Shadow mapping is a useful technique for achieving realistic lighting without a lot of 
additional processing. The light’s viewpoint can be used to determine what objects are lit 
and which remain in shadow. Depth textures are special textures designed to store the 
contents of your depth buffer for use as a shadow map. Eye linear texture coordinate 
generation is the basis for projected textures. The texture matrix can be used to reorient 
the texture coordinates back into the light’s clip space. Shadow comparison can be used to 
make the distinction between shadowed and lit regions. The GL_ARB_shadow_ambient 
extension can be used to reduce the number of passes that must be rendered. 
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Reference 


glAlphaFunc 


Purpose: 
Include File: 
Syntax: 


Sets the alpha test function. 
<gl.h> 


void glAlphaFunc(GLenum func, GLclampf ref); 


Description: 


Parameters: 


func 


ref 


Returns: 
See Also: 


This function establishes the alpha test function to be used along with a 
reference alpha value. When alpha testing is enabled, each fragment’s 
alpha value is compared against this reference value according to the 
alpha test function’s relational operator. If the comparison is not true, the 
fragment is discarded. This test occurs after the scissor test, but before 
stencil and depth testing. 


GLenum: The relational operator to use for alpha test comparisons. It can 
be one of the following constants: 


GL_ALWAYS: The alpha test will always pass. 


GL_EQUAL: The alpha test will pass if the fragment’s alpha value is equal to 
the reference value. 


GL_GEQUAL: The alpha test will pass if the fragment’s alpha value is greater 
than or equal to the reference value. 


GL_GREATER: The alpha test will pass if the fragment’s alpha value is 
greater than the reference value. 


GL_LEQUAL: The alpha test will pass if the fragment’s alpha value is less 
than or equal to the reference value. 


GL_LESS: The alpha test will pass if the fragment’s alpha value is less than 
the reference value. 


GL_NEVER: The alpha test will always fail. 


GL_NOTEQUAL: The alpha test will pass if the fragment’s alpha value is not 
equal to the reference value. 


GLclampf: The reference alpha value against which incoming alpha values 
are compared. This value is clamped to the range [0,1]. 


None. 
glDepthFunc, glScissor, glStencilFunc 


Reference 


glColorMask 

Purpose: Sets the writemask for sending colors to the framebuffer. 
Include File: <gl.h> 

Syntax: 


void glColorMask(GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha); 


Description: This function establishes the writemask used for allowing or disallowing 
writes of individual color components to the framebuffer. A true value 
indicates that the component should be written. Otherwise, the compo- 
nent will remain unwritten. 


Parameters: 

red GLboolean: The writemask selector for the red color component. 
green GLboolean: The writemask selector for the green color component. 
blue GLboolean: The writemask selector for the blue color component. 
alpha GLboolean: The writemask selector for the alpha color component. 
Returns: None. 

See Also: glDepthMask, glStencilMask 

glCopyTexSubImage 

Purpose: Replaces part of a texture image with pixels from the framebuffer. 
Include File: <gl.h> 

Syntax: 


void glCopyTexSubImage1D(GLenum target, Glint level, GLint xoffset, GLint x, GLint 
wy, GLsizei width); 

void glCopyTexSubImage2D(GLenum target, Glint level, GLint xoffset, GLint yoffset, 
wGLint x, GLint y, GLsizei width, GLsizei height) ; 

void glCopyTexSubImage3D(GLenum target, Glint level, GLint xoffset, GLint yoffset, 
wGLint zoffset, GLint x, GLint y, GLsizei width); 


Description: This function copies color or depth values out of the framebuffer, replac- 
ing some or all of the texels in a previously specified texture image. If the 
internal format of the texture is a color format, the color values are 
copied from the current GL_READ_BUFFER. If the internal format is a depth 
format, depth values are copied from the depth buffer. 
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Parameters: 

target GLenum: The target texture, which must be GL_TEXTURE_1D for 
glCopyTexSubImage1D, GL_TEXTURE_2D for glCopyTexSubImage2D, and 
GL_TEXTURE_3D for glCopyTexSubImage3D. 

level GLint: The level-of-detail mipmap array to be partially or wholly 
replaced. 

xoffset GLint: Offset in the x direction where replaced values will start. 

yoffset GLint: Offset in the y direction where replaced values will start. 

zoffset GLint: Offset in the z direction where replaced values will start. 

x GLint: The x window coordinate of the left edge of the region to copy 
from the framebuffer. 

y GLint: The y window coordinate of the lower edge of the region to copy 
from the framebuffer. 

width GLsizei: The width of the region to copy from the framebuffer. 

height GLsizei: The height of the region to copy from the framebuffer. 

Returns: None. 

See Also: glCopyPixels, glCopyTexImage, glReadBuffer, glTexImage, 
glTexSubImage 

glPolygonOffset 

Purpose: Sets the depth offset applied to polygons. 

Include File: <gl.h> 

Syntax: 


void glPolygonOffset (GLfloat factor, GLfloat units); 


Description: 


Parameters: 


factor 
units 


Returns: 
See Also: 


This function establishes the depth offset factor and units applied to 
polygons. The depth offset can be enabled and disabled individually for 
polygons in point, line, or fill mode using the tokens 
GL_POLYGON_OFFSET_POINT, GL_POLYGON_OFFSET_LINE, and 
GL_POLYGON_OFFSET_FILL, respectively. The depth offset adds or subtracts 
a single computed value for all the fragments of each polygon. If enabled, 
this occurs during rasterization. 


GLfloat: A scale factor used to generate a variable depth offset by multi- 
plying it with the maximum depth slope of the polygon. 


GLfloat: A constant depth offset, multiplied by the minimum granularity 
of the depth buffer. 


None. 
glDepthFunc, glPolygonMode 


CHAPTER 19 


Programmable Pipeline: This Isn’t 
Your Father’s OpenGL 


by Benjamin Lipchak 


WHAT YOU’LL LEARN IN THIS CHAPTER: 


¢ The responsibilities of the conventional fixed functionality OpenGL pipeline 
¢ The pipeline stages that can be replaced by new programmable pipeline shaders 
¢ The shader extensions that expose this new functionality 


Graphics hardware has traditionally been designed to quickly perform the same rigid set of 
hard-coded computations. Different steps of the computation can be skipped, and parame- 
ters can be adjusted, but the computations themselves remain fixed. That’s why this old 
paradigm of GPU design is called fixed functionality. 


There has been a trend toward designing general-purpose graphics processors. Just like 
CPUs, these GPUs can be programmed with arbitrary sequences of instructions to perform 
virtually any imaginable computation. The biggest difference is that GPUs are tuned for 
the floating-point operations most common in the world of graphics. 


Think of it this way: Fixed functionality is like a cookie recipe. OpenGL allows you to 
change the recipe a bit here and there. Change the amount of each ingredient, change the 
temperature of the oven. You don’t want chocolate chips? Fine. Disable them. But one 
way or another, you end up with cookies. 


Enter programmability. Want to pick your own ingredients? Fine. Want to cook in a 
microwave or a frying pan or on the grill? Have it your way. Instead of cookies, you can 
bake a cake or grill sirloin or heat up leftovers. The possibilities are endless. The entire 
kitchen and all its ingredients, appliances, pots, and pans are at your disposal. These are 
the inputs and outputs, instruction set, and temporary register storage of a programmable 
pipeline stage. 
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In this chapter, we cover the conventional OpenGL pipeline and then describe the parts of 
it that can be replaced by programmable stages. 


Out with the Old 


Before we talk about replacing it, let’s consider the conventional OpenGL rendering 
pipeline. The first several stages operate per-vertex. Then the primitive is rasterized to 
produce fragments. Finally, fragments are textured, fogged, and other per-fragment opera- 
tions are applied before writing each fragment to the framebuffer. Figure 19.1 diagrams the 
fixed functionality pipeline. 


The per-vertex and per-fragment stages of the pipeline are discussed separately in the 
following sections. 


Fixed Vertex Processing 


The per-vertex stages start with a set of vertex attributes as input. These attributes include 
object-space position, normal, primary and secondary colors, a fog coordinate, and texture 
coordinates. The final result of per-vertex processing is clip-space position, front-facing 
and back-facing primary and secondary colors, a fog coordinate, texture coordinates, and 
point size. What happens in between is broken into four stages. 


Vertex Transformation 

In fixed functionality, the vertex position is transformed from object space to clip space. 
This is achieved by multiplying the object space coordinate first by the modelview matrix 
to put it into eye space. Then it’s multiplied by the projection matrix to reach clip space. 


The application has control over the contents of the two matrices, but these matrix multi- 
plications always occur. The only way to “skip” this stage would be to load identity matri- 
ces, so you end up with the same position you started with. 


Each vertex’s normal is also transformed, this time from object space to eye space for use 
during lighting. The normal is multiplied by the inverse of the modelview matrix, after 
which it is optionally rescaled or normalized. Lighting wants the normal to be a unit 
vector, so unless you’re passing in unit length normal vectors and have a modelview 
matrix that leaves them unit length, you’ll need to either rescale them (if your modelview 
introduced only uniform scaling) or fully normalize them. 


Chapters 4, “Geometric Transformations: The Pipeline,” and 5, “Color, Materials, and 
Lighting: The Basics,” covered transformations and normals. 


Lighting 

Lighting takes the vertex color, normal, and position as its raw data inputs. Its output is 
two colors, primary and secondary, and in some cases a different set of colors for front and 
back faces. Controlling this stage are the color material properties, light properties, and a 
variety of glEnable/glDisable toggles. 


Out with the Old 


coordinate 
generation and 
transformation 


Rasterization of 
points, lines, 
polygons, bitmaps, 

and pixel rectangles 


including smooth, wide, 
culled, and depth offset 
primitives 


FIGURE 19.1 This fixed functionality rendering pipeline represents the old way of doing 
things. 


Lighting is highly configurable; you can enable some number of lights (up to eight or 
more), each with myriad parameters such as position, color, and type. You can specify 
material properties to simulate different surface appearances. You also can enable two- 
sided lighting to generate different colors for front- and back-facing polygons. 


933 


934 


CHAPTER 19 Programmable Pipeline: This Isn’t Your Father’s OpenGL 


You can skip lighting entirely by disabling it. However, when it is enabled, the same hard- 
coded equations are always used. See Chapters 5 and 6, “More on Colors and Materials,” 
for a refresher on fixed functionality lighting details. 


Texture Coordinate Generation and Transformation 

The final per-vertex stage of the fixed functionality pipeline involves processing the 
texture coordinates. Each texture coordinate can optionally be generated automatically by 
OpenGL. There are several choices of generation equations to use. In fact, a different mode 
can be chosen for each component of each texture coordinate. Or, if generation is 
disabled, the current texture coordinate associated with the vertex is used instead. 


Whether or not texture generation is enabled, each texture coordinate is always trans- 
formed by its texture matrix. If it’s an identity matrix, the texture coordinate is not 
affected. 


This texture coordinate processing stage is covered in Chapters 8, “Texture Mapping: The 
Basics,” and 9, “Texture Mapping: Beyond the Basics.” 


Clipping 

If any of the vertices transformed in the preceding sections happen to fall outside the view 
volume, clipping must occur. Clipped vertices are discarded, and depending on the type of 
primitive being drawn, new vertices may be generated at the intersection of the primitive 
and the view volume. Colors, texture coordinates, and other vertex properties are assigned 
to the newly generated vertices by interpolating their values along the clipped edge. Figure 
19.2 illustrates a clipped primitive. 


FIGURE 19.2 All three of this triangle’s vertices are clipped out, but six new vertices are intro- 
duced. 


Out with the Old 


The application may also enable user clip planes. These clip planes further restrict the clip 
volume so that even primitives within the view volume can be clipped. This technique is 
often used in medical imaging to “cut” into a volume of, for example, MRI data to inspect 
tissues deep within the body. 


Fixed Fragment Processing 


The per-fragment stages start out with a fragment and its associated data as input. This 
associated data is composed of various values interpolated across the line or triangle, 
including one or more texture coordinates, primary and secondary colors, and a fog coor- 
dinate. The result of per-fragment processing is a single color that will be passed along to 
subsequent per-fragment operations, including depth test and blending. Again, four stages 
of processing are applied. 


Texture Application and Environment 

Texture application is the most important per-fragment stage. Here, you take all the frag- 
ment’s texture coordinates and its primary color as input. The output will be a new 
primary color. How this happens is influenced by which texture units are enabled for 
texturing, which texture images are bound to those units, and what texture function is set 
up by the texture environment. 


For each enabled texture unit, the 1D, 2D, 3D, or cube map texture bound to that unit is 
used as the source for a lookup. Depending on the format of the texture and the texture 
function specified on that unit, the result of the texture lookup will either replace or be 
blended with the fragment’s primary color. The resulting color from each enabled texture 
unit is then fed in as a color input to the next enabled texture unit. The result from the 
last enabled texture unit is the final output for the texturing stage. 


Many configurable parameters affect the texture lookup, including texture coordinate 
wrap modes, border colors, minification and magnification filters, level-of-detail clamps 
and biases, depth texture and shadow compare state, and whether mipmap chains are 
automatically generated. Fixed functionality texturing was covered in detail in Chapters 8 
and 9. 


Color Sum 

The color sum stage starts with two inputs: a primary and a secondary color. The output is 
a single color. There’s not a lot of magic here. If color sum is enabled, or if lighting is 
enabled, the primary and secondary colors’ red, green, and blue channels are added 
together and then clamped back into the range [0,1]. If color sum is not enabled, the 
primary color is passed through as the result. The alpha channel of the result always 
comes from the primary color’s alpha. The secondary color’s alpha is never used by the 
fixed functionality pipeline. 


Fog Application 
If fog is enabled, the fragment’s color is blended with a constant fog color based on a 
computed fog factor. That factor is computed according to one of three hard-coded 
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equations: linear, exponential, or second-order exponential. These equations base the fog 
factor on the current fog coordinate, which may be the approximate distance from the 
vertex to the eye, or an arbitrary value set per-vertex by the application. 


For more details on fixed functionality fog, see Chapter 6. 


Antialiasing Application 

Finally, if the fragment belongs to a primitive that has smoothing enabled, one piece of 
associated data is a coverage value. That value is 1.0 in most cases, but for fragments on 
the edge of a smooth point, line, or polygon, the coverage is somewhere between 0.0 and 
1.0. The fragment’s alpha value is multiplied by this coverage value, which will with 
subsequent blending produce smooth edges for these primitives. Chapter 6 discussed this 
behavior. 


In with the New 


That trip down memory lane was intended to both refresh your memory on the various 
stages of the current pipeline and to give you an appreciation of the configurable but 
hard-coded computations that happen each step of the way. Now forget everything you 
just read. We’re going to replace the majority of it and roll in the new world order: 
shaders. 


Shaders are also sometimes called programs, and the terms are usually interchangeable. And 
that’s what shaders are—application-defined customized programs that take over the 
responsibilities of fixed functionality pipeline stages. I prefer the term shader because it 
avoids confusion with the typical definition of program, which can mean any old applica- 
tion. 


Figure 19.3 illustrates the simplified pipeline where previously hard-coded stages are 
subsumed by custom programmable shaders. 


Programmable Vertex Shaders 


As suggested by Figure 19.3, the inputs and outputs of a vertex shader remain the same as 
those of the fixed functionality stages being replaced. The raw vertices and all their attrib- 
utes are fed into the vertex shader, rather than the fixed transformation stage. Out the 
other side, the vertex shader spits texture coordinates, colors, point size, and a fog coordi- 
nate, which are passed along to the clipper, just like the output from the fixed functional- 
ity lighting stage. A vertex shader is a drop-in replacement for those three per-vertex 
stages. 


Replacing Vertex Transformation 

What you do in your vertex shader is entirely up to you. The absolute minimum (if you 
want anything to draw) would be to output a clip-space vertex position. Every other 
output is optional and at your sole discretion. How you generate your clip-space vertex 
position is your call. Traditionally, and to emulate fixed functionality transformation, you 
would want to multiply your input position by the modelview and projection matrices to 
get your clip-space output. 


In with the New 937 


vertices and their fragments and their 


Hyd) 


Antialiasing 


WN 


FIGURE 19.3 The block diagram looks simpler, but in reality these shaders can do everything 
the original fixed stages could do, plus more. 


But say you have a fixed projection and you’re sending in your vertices already in clip 
space. In that case, you don’t need to do any transformation. Just copy the input position 
to the output position. Or, on the other hand, maybe you want to turn your Cartesian 
coordinates into polar coordinates. You could add extra instructions to your vertex shader 
to perform those computations. 
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Replacing Lighting 

If you don’t care what the vertex’s colors are, you don’t have to perform any lighting 
computations. You can just copy the color inputs to the color outputs, or if you know the 
colors will never be used later, you don’t have to output them at all, and they will become 
undefined. Beware, if you do try to use them later after not outputting them from the 
vertex shader, undefined usually means garbage! 


If you do want to generate more interesting colors, you have limitless ways of going about 
it. You could emulate fixed functionality lighting by adding instructions that perform 
these conventional computations, maybe customizing them here or there. You could also 
color your vertices based on their positions, their surface normals, or any other input 
vector. 


Replacing Texture Coordinate Processing 

If you don’t need texture coordinate generation, you don’t need to code it into your 
vertex shader. The same goes for texture coordinate transformation. If you don’t need it, 
don’t waste precious shader cycles implementing it. You can just copy your input texture 
coordinates to their output counterparts. Or, as with colors, if you won’t use the texture 
coordinate later, don’t waste your time outputting it at all. For example, if your graphics 
card supports eight texture units, but you’re going to use only three of them for texturing 
later in the pipeline, there’s no point in outputting the other five. Doing so would just 
consume resources unnecessarily. 


You understand the input and output interfaces of vertex shaders, largely the same as their 
fixed functionality counterparts. But there’s been a lot of hand waving about adding code 
to perform the desired computations within the shader. This would be a great place for an 
example of a vertex shader, wouldn’t it? Alas, this chapter covers only the what, where, 
and why of shaders. The next four chapters are devoted to the how, so you’ll have to be 
patient and use your imagination. Consider this the calm before the storm. In a few pages, 
you'll be staring at more shaders than you ever hoped to see. 


Fixed Functionality Glue 


In between the vertex shader and fragment shader, there remains a couple of fixed func- 
tionality stages that act as glue between the two shaders. One of them is the clipping stage 
described previously, which clips the current primitive against the view volume and in so 
doing possibly adds or removes vertices. After clipping, the perspective divide by W 
occurs, yielding normalized device coordinates. These coordinates are subjected to view- 
port transformation and depth range transformation, which yield the final window-space 
coordinates. Then it’s on to rasterization. 


Rasterization is the fixed functionality stage responsible for taking the processed vertices of 
a primitive and turning them into fragments. Whether a point, line, or polygon primitive, 
this stage produces the fragments to “fill in” the primitive and interpolates all the colors 
and texture coordinates so that the appropriate values are assigned to each fragment. 
Figure 19.4 illustrates this process. 
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Point rasteriza Line resterieal Pol ce 
FIGURE 19.4 Rasterization turns vertices into fragments. 


Depending on how far apart the vertices of a primitive are, the ratio of fragments to 
vertices tends to be relatively high. For a highly tessellated object, though, you might find 
all three vertices of a triangle mapping to the same single fragment. As a general rule, 
significantly more fragments are processed than vertices, but as with all rules, there are 
exceptions. 


Rasterization is also responsible for making lines the desired width and points the desired 
size. It may apply stipple patterns to lines and polygons. It generates partial coverage 
values at the edges of smooth points, lines, and polygons, which later are multiplied into 
the fragment’s alpha value during antialiasing application. If requested, rasterization culls 
out front- or back-facing polygons and applies depth offsets. 


In addition to points, lines, and polygons, rasterization also generates the fragments for 
bitmaps and pixel rectangles (drawn with glDrawPixels), But these primitives don’t origi- 
nate from normal vertices. Instead, where interpolated data is usually assigned to frag- 
ments, those values are adopted from the current raster position. See Chapter 7, “Imaging 
with OpenGL,” for more details on this subject. 


Programmable Fragment Shaders 

The same texture coordinates, fog coordinate, and colors are available to the fragment 
shader as were previously available to the fixed functionality texturing stage. The same 
single color output is expected out of the fragment shader that was previously expected 
from the fixed functionality fog stage. Just as with vertex shaders, you may choose your 
own adventure in between the input interface and output interface. 


Replacing Texturing 

The single most important capability of a fragment shader is performing texture lookups. 
For the most part, these texture lookups are unchanged from fixed functionality in that 
most of the texture state is set up outside the fragment shader. The texture image is speci- 
fied and all its parameters are set the same as though you weren’t using a fragment shader. 
The main difference is that you decide within the shader when and if to perform a lookup 
and what to use as the texture coordinate. 


You’re not limited to using texture coordinate 0 to index into texture image 0. You can 
mix and match coordinates with different textures, using the same texture with different 
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coordinates or the same coordinate with different textures. Or you can even compute a 
texture coordinate on the fly within the shader. This flexibility was impossible with fixed 
functionality. 


The texture environment previously included a texture function that determined how the 
incoming fragment color was mixed with the texture lookup results. That function is now 
ignored, and it’s up to the shader to combine colors with texture results. In fact, you 
might choose to perform no texture lookups at all and rely only on other computations to 
generate the final color result. A fragment shader could simply copy its primary color 
input to its color output and call it a day. Not very interesting, but such a “passthrough” 
shader might be all you need when combined with a fancy vertex shader. 


Replacing Color Sum 

Replacing the color sum is simple. This stage just adds together the primary and secondary 
colors. If that’s what you want to happen, you just add an instruction to do that. If you’re 
not using the secondary color for anything, ignore it. 


Replacing Fog 

Fog application is not as easy to emulate as color sum, but it’s still reasonably easy. First, 
you need to calculate the fog factor, which is an equation based on the fragment’s fog 
coordinate and some constant value such as density. Fixed functionality dictated the use 
of linear, exponential, or second-order exponential equations, but with shaders you can 
make up your own equation. Then you blend in a constant fog color with the fragment’s 
unfogged color, using the fog factor to determine how much of each goes into the blend. 
You can achieve all this in just a handful of instructions. Or you can not add any instruc- 
tions and forget about fog. The choice is yours. 


Introduction to Shader Extensions 


Enough with the hypotheticals. If you’ve made it this far, you must have worked up an 
appetite for some real shaders by now. In the following sections, we introduce the differ- 
ent OpenGL extensions that expose programmable shaders. These extensions were devel- 
oped and approved by the OpenGL Architecture Review Board (ARB), and as such are 
widely supported by graphics card vendors throughout the industry. 


Low-Level Extensions 


The low-level extensions are GL_ARB_vertex_program and GL_ARB_fragment_program, used 
for replacing the fixed functionality vertex stages and fragment stages, respectively. 


Much like assembly language versus C, this first set of extensions operates at a low level, 
giving more direct access to the features and resources of the GPU. As with assembly 
language, you make the trade-off between programming at a more cumbersome, detail- 
oriented, and often complex level in exchange for the full control of the hardware and 
improved performance. 


re 
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Strictly speaking, you’re not really coding at the assembly level because each hardware 
vendor has a unique GPU design, each with its own native instruction representation and 
instruction set. Each has its own limits on the number of registers, constants, and instruc- 
tions. What you’re capturing in these low-level extensions is just the lowest common 
denominator of functionality that’s available from all vendors. 


Listings 19.1 and 19.2 are your first exposure to these low-level shaders. Consider them to 
be “Hello World” shaders, even though technically they don’t say hello at all. 


LISTING 19.1 A Simple GL_ARB_vertex_program Vertex Shader 


! LARBvp1.@ 
# This is our Hello World vertex shader 
# notice how comments are preceded by '‘#' 


ATTRIB iPos = vertex.position; # input position 
ATTRIB iPrC = vertex.color.primary; # input primary color 


QUTPUT oPos = result.position; # output position 
QUTPUT oPrC = result.color.primary; # output primary color 
OUTPUT oScC = result.color.secondary; # output secondary color 


PARAM mvp[4] = { state.matrix.mvp };  # modelview * projection matrix 
TEMP tmp; # temporary register 


DP4 tmp.x, iPos, mvp[Q]; # Multiply input position by MVP 
DP4 tmp.y, iPos, mvp[1]; 
DP4 tmp.z, iPos, mvp[2]; 
DP4 tmp.w, iPos, mvp[3]; 


MOV oPos, tmp; # Output clip-space coord 

MOV oPrC, iPr; # Copy primary color input to output 
RCP tmp.w, tmp.w; # tmp now contains 1/W instead of W 
MUL tmp.xyz, tmp, tmp.w; # tmp now contains persp-divided coords 
MAD oScC, tmp, 0.5, 0.5; # map from [-1,1] to [0,1] and output 
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LISTING 19.2 A Simple GL_ARB_fragment_program Fragment Shader 


!!ARBfp1.0 
# This is our Hello World fragment shader 


ATTRIB iPrC = fragment.color.primary; # input primary color 
ATTRIB iScC = fragment.color.secondary; # input secondary color 


OUTPUT oCol = result.color; # output color 

LRP oCol.rgb, @.5, iPrC, iScC; # 50/50 mix of two colors 

MOV oCol.a, iPrC.a; # ignore secondary color alpha 
END 


If these shaders are not self-explanatory, don’t despair! Chapter 20, “Low-Level Shading: 
Coding to the Metal,” will make sense of it all. Basically, the vertex shader emulates fixed 
functionality vertex transformation by multiplying the object-space vertex position by the 
modelview/projection matrix. Then it copies its primary color unchanged. Finally, it 
generates a secondary color based on the post-perspective divide normalized device coordi- 
nates. Because they will be in the range [-1,1], you also have to divide by 2 and add 1/2 to 
get colors in the range [0,1]. The fragment shader is left with the simple task of blending 
the primary and secondary colors together. Figure 19.5 shows a sample scene rendered 
with these shaders. 


3 Low-level Shaders Demo 
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FIGURE 19.5 The colors are pastel tinted by the objects’ positions in the scene. 
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High-Level Extensions 

Programming GPUs in a high-level language means less code, more readable code, and 
thus more productivity. The OpenGL Shading Language (GLSL) is the name of this 
language. It looks a lot like C, but with built-in data types and functions that are useful to 
vertex and fragment shaders. 


Four extensions are involved here: GL_ARB_shader_objects, GL_ARB_vertex_shader, 
GL_ARB_fragment_shader, and GL_ARB_shading_language_100. The first extension 
describes the mechanism for loading and switching between shaders and is shared by the 
next two extensions, one covering vertex shader specifics and one for fragment shader 
specifics. The fourth extension describes the GLSL language itself, again shared by vertex 
shaders and fragment shaders. 


There is a confusing similarity in extension names between the low level and the high 
level: GL_ARB_*_program versus GL_ARB_* shader. Just remember that the low-level ones 
are called programs, and the high-level ones are called shaders. This distinction is reinforced 
only by their extension names. In reality, they’re all shaders. 


Notice how Listings 19.3 and 19.4, which perform the same computations as the low-level 
Hello World shaders, are representable in fewer lines of more readable code. 


LISTING 19.3 A Simple GLSL Vertex Shader 


void main(void) 


{ 


// This is our Hello World vertex shader 
// notice how comments are preceded by '//' 


// normal MVP transform 
vec4 clipCoord = gl_ModelViewProjectionMatrix * gl Vertex; 
gl_Position = clipCoord; 


// Copy the primary color 
gl_FrontColor = gl Color; 


// Calculate NDC 
vec3 nde = clipCoord.xyz / clipCoord.w; 


// Map from [-1,1] to [@,1] before outputting 
gl_SecondaryColor = (ndc * 0.5) + 0.5; 
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LISTING 19.4 A Simple GLSL Fragment Shader 
// This is our Hello World fragment shader 
void main(void) 


{ 


// Mix primary and secondary colors, 50/50 
gl_FragColor = mix(gl_Color, vec4(vec3(gl_SecondaryColor), 1.0), 0.5); 


Chapter 21, “High-Level Shading,” will help you understand this code if it isn’t readable 
enough already. 


Summary 


In this chapter, we outlined the conventional per-vertex and per-fragment pipeline stages, 
setting the stage for their wholesale replacement by programmable stages. We briefly intro- 
duced both the low-level and high-level shading extensions that step in for their fixed 
functionality counterparts. 


High-level shader compilers are improving rapidly, and like C compilers, they soon will be 
generating hardware code that’s as good or better than hand-coded assembly. Although 
the low-level extensions are currently very popular, expect the high-level extensions to 
gain mindshare in the near future as GPU compiler technology continues to advance. 


CHAPTER 20 


Low-Level Shading: Coding to the 
Metal 


by Benjamin Lipchak 
WHAT YOU'LL LEARN IN THIS CHAPTER: 
How To Functions You'll Use 
Specify shader text glProgramStringARB 
Switch between shaders glBindProgramARB 
Create and delete shaders glGenProgramsARB/glDeleteProgramsARB 
Set program parameters glProgramEnvParameter*ARB/glProgramLocalParameter*ARB 
Query program parameters g1GetProgramEnvParameter*ARB/glGetProgramLocalParameter*ARB 
Set vertex attributes glVertexAttrib*ARB/glVertexAttribPointerARB 
glEnableVertexAttribArrayARB/glDisableVertexAttribArrayARB 
Query vertex attributes glGetVertexAttrib*vARB/glGetVertexAttribPointervARB 


Query program object state glGetProgramivARB/glGetProgramStringARB/glIsProgramARB 


Low-level shaders provide relatively direct access to the current generation of underlying 
shader hardware. Every cycle of the shader can be scheduled with a vector instruction that 
operates on four components at a time. Low-level vertex and fragment shaders use the 
same commands for loading and managing shaders, and they offer nearly the same 
instruction sets. Their biggest difference is in their inputs and outputs. 


As described in Chapter 19, “Programmable Pipeline: This Isn’t Your Father's OpenGL,” 
vertex shaders take unprocessed vertices and their attributes (position, normal, colors, 
texture coordinates, and so on), and output clip-space position and new processed attrib- 
utes (colors, texture coordinates, and so on). Fragment shaders, on the other hand, take 
fragments and their associated data as input, and they output a final fragment color and 
possibly a new depth. 
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We could devote an entire book to shaders, but we’ll try to cover all the most important 
aspects in this chapter. Feel free to consult the extension specifications 
(GL_ARB_vertex_program and GL_ARB_fragment_program) as a complete reference. After 
you read this chapter, those specs may actually be decipherable! 


Managing Low-Level Shaders 


In the following sections, we describe mostly what goes on inside the shader. First, 
though, you need to load shaders into OpenGL and be able to turn shaders on and off and 
switch between them. Then you can start writing shaders. 


Creating and Binding Shaders 

Like texture objects, buffer objects, occlusion queries, and other OpenGL objects, low-level 
shaders are loaded into objects, too—program objects in this case. First, you generate an 
unused program object name and then create it by binding it for the first time: 


// Create shader objects, set shaders 
glGenProgramsARB(2, ids); 
g1BindProgramARB(GL_VERTEX_PROGRAM_ARB, ids[]); 
g1BindProgramARB(GL_FRAGMENT_PROGRAM_ARB, ids[1]); 


In its initial state, the program object has no shader associated with it. If you try enabling 
it and drawing something, an error is thrown. So now you're ready to load up some real 
shaders. 


Loading Shaders 


You pass shaders into OpenGL as ASCII strings via g1ProgramStringARB, which takes a 
shader type, format, length, and pointer to the string containing the shader text: 


glProgramStringARB(GL_VERTEX_PROGRAM_ARB, GL_PROGRAM_FORMAT_ASCII_ARB, 
strlen(vpString), vpString) ; 

glProgramStringARB(GL_FRAGMENT_PROGRAM_ARB, GL_PROGRAM_FORMAT_ASCII_ARB, 
strlen(fpString), fpString); 


The first argument indicates whether you’re replacing the currently bound low-level vertex 
shader or fragment shader. 


The format argument is used just for future expandability, such as to accept a possible 
Unicode or binary bytecode representation. Currently, GL_PROGRAM_FORMAT_ASCII_ARB is 
the only game in town. 


Your string need not be null-terminated. g1ProgramStringARB looks only at the number of 
characters you tell it to in the third argument, and those characters should all be part of 
the actual shader text. A null terminator, if it is present, should not be included in the 
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length argument you pass in. Conveniently, the standard C string function strlen 
behaves this way, returning the length of a string minus its terminator. 


When OpenGL receives the glProgramStringARB command, it proceeds to parse the 
shader. If all goes well, your shader is compiled and optimized as necessary for the under- 
lying hardware and is ready for rendering when you enable vertex and/or fragment 
shading. 


If you have any syntax or semantic errors, or if the shader is too complex for the imple- 
mentation to handle, an error is thrown. In this case, the currently bound shader is not 
replaced, and whatever shader was there before (if any) remains in place. You can find out 
where and why a problem occurred by querying for the error position and error string. 


The error position is the byte offset into the shader string where the error occurred. If no 
error occurs, you get back -1. If the error is a semantic restriction that can be discovered 
only after the whole shader is parsed (for example, trying to use the same texture unit for 
both 2D and 3D texturing), the error position is set to the length of the shader. 


The error string is the most useful way to diagnose your problem. It tells you the type of 
error that occurred and may provide additional hints, such as the line number where the 
error occurred. Using the error string to find the error in your shader is a lot easier than 
using the error position and trying to count out hundreds of characters by hand!) 


Listing 20.1 shows the code used to set up low-level shaders. 


LISTING 20.1 Setting Up Low-Level Shaders 


// Create, set and enable shaders 
glGenProgramsARB(2, ids); 


glBindProgramARB(GL_VERTEX_PROGRAM_ARB, ids[Q]); 
glProgramStringARB(GL_VERTEX_PROGRAM_ARB, GL_PROGRAM_FORMAT_ASCII_ARB, 
strlen(vpString), vpString); 
glGetIntegerv(GL_PROGRAM_ERROR_POSITION_ARB, &errorPos) ; 
if (errorPos != -1) 
{ 
fprintf(stderr, “Error in vertex shader at position %d!\n", errorPos); 
fprintf(stderr, "Error string: %s\n", 
glGetString(GL_PROGRAM_ERROR_STRING_ARB) ) ; 
Sleep (5000) ; 
exit(Q); 


g1BindProgramARB(GL_FRAGMENT_PROGRAM_ARB, ids[1]); 
g1lProgramStringARB(GL_FRAGMENT_PROGRAM_ARB, GL_PROGRAM_FORMAT_ASCII_ARB, 
strlen(fpString), fpString) ; 
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LISTING 20.1 Continued 
glGetIntegerv(GL_PROGRAM_ERROR_POSITION_ARB, &errorPos) ; 


if (errorPos != -1) 
{ 


fprintf(stderr, "Error in fragment shader at position %d!\n", errorPos) ; 

fprintf(stderr, "Error string: %s\n", 
glGetString(GL_PROGRAM_ERROR_STRING_ARB)) ; 

Sleep (5000) ; 

exit(Q); 


if (useVertexShader) 
glEnable(GL_VERTEX_PROGRAM_ARB) ; 

if (useFragmentShader) 
glEnable(GL_FRAGMENT_PROGRAM_ARB) ; 


Try adding a typographical error into one of the shaders loaded by the sample code in 
Listing 20.1. See how well the error string on your OpenGL implementation helps you 
narrow down the problem. 


Deleting Shaders 


With shaders, just like other OpenGL objects, you need to clean up after yourself when 
you’re done. Deleting your shaders frees the resources and makes the names available for 
use again later: 


glDeleteProgramsARB(2, ids); 


Setting Up the Extensions 


One more detail stands between us and diving into the actual shaders. Low-level vertex 
and fragment shaders are not part of core OpenGL. In previous chapters, we covered func- 
tionality that used to be extensions but have since been promoted to the core. However, 
with high-level shaders gaining popularity, these low-level shaders will likely never be 
promoted and will live their lives forever as ARB-approved extensions. 


Their extension status does not make much difference when it comes to using them. At 
least on Windows platforms, any functionality more recent than OpenGL 1.1, whether 
core or extension, requires its entrypoint function pointers to be queried before use. Before 
doing that, you must check also for the presence of the extensions in the extension string. 
The sample code also uses the secondary color feature, which either requires OpenGL 1.4 
or the GL_EXT_secondary_color extension. Listing 20.2 shows how to check whether an 
OpenGL implementation supports the required features. 
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LISTING 20.2 Checking for the Presence of OpenGL Features 


// Make sure required functionality is available! 
if (!gltIsExtSupported("GL_ARB_vertex_program") ) 


{ 
fprintf(stderr, "GL_ARB_vertex_program extension is unavailable! \n"); 
Sleep (2000) ; 
exit(Q); 
} 
if (!gltIsExtSupported("GL_ARB_fragment_program") ) 
{ 
fprintf(stderr, "GL_ARB_fragment_program extension is unavailable! \n"); 
Sleep (2000) ; 
exit(Q); 
} 
version = glGetString(GL_VERSION) ; 
if (((version(®] != '1') {| (version[1] != '.') |} 
(version[2] < '4') || (version[2] > '9')) && // 1.4+ 
(!gltIsExtSupported("GL_EXT_secondary_color"))) 
{ 
fprintf(stderr, “Neither OpenGL 1.4 nor GL_EXT_secondary_color" 
"extension is available!\n"); 
Sleep (2000) ; 
exit(0); 
} 


glGenProgramsARB = gltGetExtensionPointer("glGenProgramsARB" ) ; 
glBindProgramARB = gltGetExtensionPointer("glBindProgramARB") ; 
glProgramStringARB = gltGetExtensionPointer("glProgramStringARB") ; 
glDeleteProgramsARB = gltGetExtensionPointer("glDeleteProgramsARB") ; 
if (gltIsExtSupported("GL_EXT_secondary_color") ) 

glSecondaryColor3f = gltGetExtensionPointer("glSecondaryColor3fExT") ; 
else 

glSecondaryColor3f = gltGetExtensionPointer("glSecondaryColor3f") ; 


if (1!glGenProgramsARB || !g1BindProgramARB |} !glProgramStringARB !! 
!glDeleteProgramsARB || !glSecondaryColorsf) 


fprintf(stderr, "Not all entrypoints were available!\n"); 
Sleep (2000); 
exit(Q); 
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Instruction Sets 


Each cycle, or instruction slot, of a low-level vertex or fragment shader can have a differ- 
ent instruction opcode, such as ADD, MUL, or MOV, to perform addition, multiplication, or 
copy, respectively. These opcodes are your basic shader building blocks. Most instruction 
opcodes are followed by a single output and one or more inputs, separated by commas. 
Each instruction ends with a semicolon. 


MUL myResult, myTemp, 2.0; # multiplies each component of myTemp by 2, 
# stores in myResult 


With few exceptions, the vertex shader and fragment shader instruction sets are identical. 
In the following sections, we first discuss the significant overlap between the two, and 
then we deal with the instructions that are specific to one shader type or the other. 


Common Instructions 

The instruction set can be categorized by the number of input arguments, whether the 
inputs are vector or scalar, and whether the result is vector or scalar. Vector in this case 
means a four-component vector, whereas a scalar is a single component. Table 20.1 catego- 
rizes all the instructions that are common to both vertex shaders and fragment shaders. 


TABLE 20.1 Common Instruction Set 


Instruction —_ Inputs Output Description 

ABS 1 vector vector Takes the absolute value of the input vector. 

ADD 2 vectors vector Adds two vectors together. 

DP3 2 vectors scalar Takes the dot product of the first three components of input 
vectors. 

DP4 2 vectors scalar Takes the dot product of all four components of input vectors. 

DPH 2 vectors scalar Takes the dot product of the first three components of input 
vectors and adds in the fourth component of the second 
input. 

DST 2 vectors vector Computes a distance vector given two specially formatted 
input vectors; see the specification for details. 

EX2 1 scalar scalar Computes 2 to the power of the scalar input. 

FLR 1 vector vector Takes the floor—that is, the largest integer less than or equal 
to the input. 

FRC 1 vector vector Takes the fractional portion, or the part left over after 
subtracting the floor from the input. 

LG2 1 scalar scalar Computes the base 2 logarithm of the scalar input. 

LIT 1 vector vector Computes lighting coefficients given a specially formatted 


input vector; see the specification for details. 
MAD 3 vectors vector Multiplies the first two vectors and then adds the third. 


Instruction 


SGE 


SLT 


XPD 


Inputs 

2 vectors 
2 vector 
1 vector 
2 vectors 


2 scalars 
1 scalar 
1 scalar 
2 vectors 


2 vectors 


2 vectors 
1 vector 


2 vectors 


Output 
vector 
vector 
vector 
vector 


scalar 
scalar 
scalar 
vector 


vector 


vector 
vector 


vector 
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Description 


Takes the maximum of each component of the two input 
vectors. 

Takes the minimum of each component of the two input 
vectors. 

Copies the vector. 

Multiplies two vectors together. 

Computes the first scalar input to the power of the second 
scalar input. 

Takes the reciprocal of the scalar input. 

Takes the reciprocal of the square root of the absolute value 
of the scalar input. 

Results in 1 for an output component if the corresponding 
component of the first input vector is greater than or equal to 
its counterpart in the second input vector; otherwise 0. 
Results in 1 for an output component if the corresponding 
component of the first input vector is less than its counterpart 
in the second input vector; otherwise 0. 

Subtracts the second vector from the first. 

Copies but with extended swizzling capabilities such as swiz- 
zling in 0 or 1 and per-component negate; see the specifica- 
tion for details. 

Computes the cross product of the first three components of 
each input vector; the fourth component is undefined. 


All instructions that output a vector operate independently on each component of the 
vector. For example, MUL actually performs four independent multiplication operations: 


MUL myResult, 
# This is the 
myResult.x 
myResult.y 
myResult.z 
myResult.w 


i 


myTemp1, myTemp2; 


same as: 

= myTemp1.x 
= myTemp1.y 
myTemp1.z 
myTemp1.w 


* myTemp2.x 
* myTemp2.y 
* myTemp2.z 
* myTemp2.w 


On the other hand, instructions that output a single scalar actually replicate that scalar to 


all components of the result vector: 


RCP myResult, 
# This is the 
# myResult.x 


myTemp.x; 
same as: 


= myResult.y = myResult.z = myResult.w = 1.0 / myTemp.x 
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Vertex-Specific Instructions 


Only three instructions are specific to low-level vertex shaders: ARL, EXP, and LOG. Table 
20.2 describes these instructions. 


TABLE 20.2  Vertex-Specific Instruction Set 


Instruction Inputs Output Description 
ARL 1 vector address Loads an address register. 
EXP 1 scalar vector Computes a rough approximation of 2 to the power of the 


scalar input with special output formatting; see the specifica- 
tion for details. 

LOG 1 scalar vector Computes a rough approximation of the base 2 logarithm of 
the scalar input with special output formatting; see the spec- 
ification for details. 


The ARL instruction is a special-purpose instruction used to load an address register, which 
is a single-component signed integer register type used for relative addressing. Before the 
address register is loaded, the address is floored so that it becomes the greatest integer less 
than or equal to the scalar input. We discuss relative addressing in a later section, 
“Addresses.” 


The EXP and LOG instructions are lower precision approximations of their EX2 and LG2 
counterparts, except they put the result only in the third component of the result vector. 
The first two components are filled with some other marginally useful approximation 
factors, and the fourth component is 1. Because these instructions provide no additional 
benefit except possibly improved performance on some OpenGL implementations, they 
were removed from the fragment shader instruction set. 


Fragment-Specific Instructions 


After the low-level vertex program extension was approved by the ARB, work began on a 
counterpart fragment program extension. All the instructions from the vertex extension 
were considered for inclusion, and only the three listed in Table 20.2 were removed. 


Relative addressing within fragment shaders is not yet a feature available in today’s hard- 
ware, so the ARL instruction was not included. Also, the low-precision EXP and LOG instruc- 
tions were not particularly interesting compared to the full-precision versions, so they 
were dropped as well. 


Quite a number of instructions particularly useful in the fragment domain were added. 
Table 20.3 lists them. 
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TABLE 20.3 Fragment-Specific Instruction Set 


Instruction 


CMP 


cos 


KIL 


LRP 


scs 


SIN 


TEX 


TXB 


TXP 


Inputs 


3 vectors 


1 scalar 


1 vector 


3 vectors 


1 scalar 


1 scalar 
1 vector 


1 vector 


1 vector 


Output 


vector 


scalar 


none 


vector 


2 scalars 


scalar 
vector 


vector 


vector 


Description 


Copies component from the second input if the first input’s 
component is less than zero; otherwise copies component 
from the third input. 

Computes the cosine of the scalar input, which is in radians 
and need not be in the range [-PI,PI]. 

Kills the current fragment processing and bypasses subsequent 
pipeline stages if any component of the input vector is less than 
zero. 

Interpolates linearly between the second and third input vectors 
based on the first input vector, as in r = i0*i1 + (1-i0)*i2. 
Computes both the cosine in the first component and sine in 
the second component based on the scalar input, which must 
be radians in the range [-PI,PI]. 

Computes the sine of the scalar input, which is in radians and 
need not be in the range [-PI,PI]. 

Performs a nonprojective texture lookup using the input 
vector’s first three components as the texture coordinate. 
Performs a nonprojective texture lookup using the input 
vector’s first three components as the texture coordinate and 
the fourth component as an LOD bias. 

Performs a projective texture lookup whereby the input vector’s 
first three components are first divided by its fourth component 
before being used as the texture coordinate. 


Fragment shaders introduce a new type of instruction: the texture instruction. The rest of 
the instructions fall into the ALU category because they perform arithmetic operations. 
TEX, TXB, and TXP are the three instructions that fall nicely into this new texture category. 


Each of these first three texture instructions performs a texture lookup on the specified 
texture target (1D, 2D, 3D, CUBE) of the specified texture unit. For example, to sample 
from the cube map on texture unit 0, you use 


TEX myResult, myTexCoord, texture[®], CUBE; 


KIL, a unique instruction that can be used to stop all further fragment shader execution 
and discard the fragment, actually falls into the texture instruction category, too. It 
doesn’t perform a texture lookup, but it may be implemented in hardware using the same 


resources. 
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Variable Types 


The instruction set is great, but those opcodes won’t do a thing for you without data to 
operate on and a place to store the result. The six different types of variables described in 
Table 20.4 can be used as inputs and/or outputs in your low-level shaders. 


TABLE 20.4 Variable Types 


Variable Type Declaration Access Description 

Temporary TEMP read-write This is a standard all-purpose temporary storage 
register. 

Parameter PARAM read-only This is a constant register that never changes over 
the course of shader execution. 

Attribute ATTRIB read-only This is a shader input. 

Output OUTPUT write-only This is a shader output. 

Address ADDRESS write-only This is a signed integer constant, available only 
within vertex shaders. 

Alias ALIAS n/a This is just another variable name given to a variable 


of one of the other types. 


All variables represent four-component floating-point vectors, except for address registers, 
which are signed integers. 


Temporaries 

Temporaries are the main work horses of low-level shaders. Unless you’re writing to an 
output register, chances are you’re writing to a temp. Before you can use a variable as a 
temp, you have to declare it. You can declare multiple temps at the same time if you want: 


TEMP diffuseColor, specColor, myTexCoord; 


Now you can use these variable names as inputs or outputs of any instruction. 


Parameters 


Parameters are variables that never change during each run of a shader. You can think of 
them as constants, except that some parameters actually can be changed outside the 
shader. In any case, you can’t write to a parameter during shader execution. You can use 
them only as instruction inputs. The three types of parameters are inline constants, state- 
bound parameters, and program parameters. Parameters can be declared with variable names, 
but they don’t have to be, as we illustrate in the following sections. 


Inline Constants 
Inline constants really are constants. They’re set to specific values within the text of the 
shader, and they can never change. You can either set all four components of the vector to 
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the same value, set each component to a unique value, or have unspecified components 
filled out with default values: 


PARAM two = 2.0; # all 4 components contain 2 

PARAM quarters = { 0.0, 0.25, 0.5, 0.75 }; # 4 unique values 

PARAM pi = { 3.14159 }; # vector gets padded out to 
# PI, 0, 0, 1 


Be aware of the subtle differences between the use of braces and no braces! For example, 
2.0 and {2.0} both have the same value in the first component, but the other three 
components differ. This is a common low-level shader writing pitfall. 


You don’t need to declare parameters if you don’t want to. You can use them directly as 
instruction inputs: 


MUL tripleCoord, myCoord, 3.0f; 
MUL scaledResult, {@.1, @.2, 0.3, 0.4}, myResult; 


State-Bound Parameters 

For convenience, you can access a variety of OpenGL state in the form of state-bound 
parameters. When OpenGL state changes, the parameters are automatically updated to 
reflect the changes. This makes emulating fixed functionality more straightforward. For 
example, instead of manually loading up the modelview/projection (MVP) matrix into 
four parameter vectors, you can just use the MVP already available in OpenGL state to 
transform your vertex position: 


DP4 result.position.x, vertex.position, state.matrix.mvp.row[Q]; 
DP4 result.position.y, vertex.position, state.matrix.mvp.row[1]; 
DP4 result.position.z, vertex.position, state.matrix.mvp.row[2]; 
DP4 result.position.w, vertex.position, state.matrix.mvp.row[3]; 


Bindable state includes all transformation matrices and the properties of texture coordi- 
nate generation, color material, lighting, fog, clip planes, point size and attenuation, 
texture environment colors, and depth range. Some bindable state parameters are specific 
to vertex shaders or specific to fragment shaders. Refer to the GL_ARB_vertex_program and 
GL_ARB_fragment_program extension specifications for the complete list of state parameter 
bindings available to low-level vertex and fragment shaders. 


Program Parameters 

In addition to the inline constants hard-coded into the text and the parameters bound to 
specific OpenGL state, you can use a third category of generic parameters. They can be 
loaded with any values and then reloaded later with different values. 


Program parameters are divided into two categories: program local and program environment 
parameters. The local ones are specific to a single shader, whereas the environment para- 
meters are shared by all shaders of a given type. That is, vertex shaders share one set of 
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environment parameters, and fragment shaders share their own set. The parameters are 
loaded with the commands g1ProgramLocalParameter4*ARB and 
glProgramEnvParameter4*ARB, which take a slot number and four values. They are then 
referenced by program. local[n] and program.env[n] within the shader text. 


So, if parameters are constants, why would you want to use program parameters instead of 
just hard-coding the constants into your shader? Certainly, the shader would be more 
readable if the constant value were explicit in the shader text. Let’s consider an example. 
Maybe you’re rendering a scene with a flickering candle, and the brightness of the flicker 
changes with every frame of rendering. You might have a shader that ends with some- 
thing like this: 


MUL finalColor, 1itColor, program.local[®]; # local ® contains flicker factor 
# in range [0,1] 


You could then reuse the shader unchanged and simply update the local parameter once 
per frame: 


glProgramLocalParameter4fARB(GL_FRAGMENT_PROGRAM_ARB, 0, 

Q.75f, 0.75f, 0.75f, 0.75f); 
renderScene(); 
glProgramLocalParameter4fARB(GL_FRAGMENT_PROGRAM_ARB, 20, 

Q.2f, 0.2f, 0.2f, 0.2F); 
renderScene(); 
glProgramLocalParameter4fARB(GL_FRAGMENT_PROGRAM_ARB, 0, 

@.5f, ©.5f, O.5f, O.5f); 
renderScene(); 


The parameter is constant during each execution of the vertex or fragment shader, but it 
isn’t constant over all rendered primitives over time. You can change program parameters 
(or state-bound parameters for that matter) as often as you like outside g1Begin/glEnd 
pairs. 


Parameter Arrays 

You can declare an array of parameters that can be indexed either with absolute addressing 
or relative addressing. With absolute addressing, you supply the exact array index you 
want to use. Relative addressing is discussed later in the section “Addresses.” 


The following are some examples of parameter array declarations. You can declare the 
array size if you want or let it be sized automatically. If you declare the size but then 
provide values beyond the size you declared, the shader will fail to parse: 


# This one is explicitly sized to 1@ vectors 
PARAM myArray[10] = {2.@, {0.1, @.2, 0.3, 0.4}, program.env[®@..5], 
state.fog.color, -1.Q}; 


Variable Types 


# This one automatically gets sized to 6 vectors 
PARAM myOtherArray[] = { state.matrix.mvp, state.matrix.texture[Q0].row[1..2] }; 


Absolute addressing of the arrays is simply a matter of providing an index when using it 
in an instruction: 


# Scale by 2, then subtract 1 courtesy of the multiply then add (MAD) instruction 
MAD scaledAndBiased, myColor, myArray[®], myArray[9]; 


Attributes 

Like parameters, attributes are also read-only inputs. But unlike parameters, attributes tend 
to change on a per-execution basis. Each new vertex being shaded has a new position, and 
possibly new input colors and texture coordinates. The same is true of each fragment. 


With attributes, like parameters, you can choose to declare them up front, or you can use 
them directly within an instruction: 


TEMP nDotC; 
ATTRIB vNorm = vertex.normal; # declared attribute 
DP3 nDotC, vNorm, vertex.color.primary; # color was not declared 


Vertex shaders and fragment shaders have their own sets of input attributes, so we cover 
them separately. 


Vertex Attributes 

Table 20.5 lists all the input attributes available to vertex shaders. They correspond to all 
the OpenGL current vertex state that can be changed per-vertex within a glBegin/glEnd 
pair. 


TABLE 20.5 Vertex Attributes 


Attribute Binding Components Description 
vertex.position (x,y,2,W) Object-space position 
vertex.normal (x,y,Z,1) Normal 

vertex.color (r,g,b,a) Primary color 
vertex.color.primary (r,g,b,a) Primary color 

vertex. color. secondary (r,g,b,a) Secondary color 

vertex. fogcoord (f,0,0,1) Fog coordinate 

vertex. texcoord (s,t,,q) Texture coordinate on unit 0 
vertex.texcoord[n] (s,t,1,q) Texture coordinate on unit n 
vertex.attrib[n] (x,y,Z,W) Generic attribute n 


The one vertex attribute you’ve probably never seen before is the generic attribute. These 
attributes have been introduced so that you can specify any kind of per-vertex data, not 
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necessarily one of the kinds previously available with fixed functionality. Binormals, 
tangent vectors, you name it—anything you'd like to stream into a vertex shader, you can 
send in through a generic attribute. 


You can use the many flavors of the glVertexAttrib*ARB command to set these generic 
attributes, or you can put generic attributes in a vertex array using 
glVertexAttribPointerARB and glEnableVertexAttribArrayARB. 


One point to keep in mind is that on some implementations, these generic attributes 
overlap with the fixed functionality attributes. One important case is that calling 
glVertexAttrib on attribute 0 is guaranteed to be the same as calling glVertex, and vice 
versa. But you need to be more careful with all the other possible aliasing conflicts. Table 
20.6 lists the conflicts between generic and fixed functionality attributes. 


TABLE 20.6 Vertex Attribute Aliasing 


Generic Binding Overlapping Attribute Overlapping Binding 
vertex.attrib[Q] Vertex position vertex. position 
vertex.attrib[1] None none 

vertex.attrib[2] Normal vertex.normal 
vertex.attrib[3] Primary color vertex.color, vertex.color.primary 
vertex.attrib[4] Secondary color vertex.color.secondary 
vertex.attrib[5] Fog coordinate vertex. fogcoord 
vertex.attrib[6] None none 

vertex.attrib[7] None none 

vertex.attrib[8] Texture coordinate 0 vertex.texcoord 
vertex.attrib[8+n] Texture coordinate n vertex. texcoord[n] 


If you call the command to change one attribute on each line of the table, the other 
becomes undefined (for example, calling gl1VertexAttrib on attribute 2 undefines the 
normal set with glNormal, and vice versa). Also, you cannot bind to both attributes on 
each line of the table within the same shader, or your shader will fail to parse. This helps 
catch accidental aliasing bugs. This result would occur if, for example, you tried to use 
both vertex.attrib[4] and vertex.color.secondary within your shader. 


Fragment Attributes 

Fragment attributes are the fragment’s position and other associated data, interpolated 
across the primitive. No generic attributes are available here—just the same interpolants 
available via fixed functionality. Table 20.7 lists all the fragment attributes and their frag- 
ment shader bindings. 


TABLE 20.7 Fragment Attributes 


Variable Types 


Attribute Binding 


fragment.position 


fragment.color 
fragment.color.primary 
fragment.color.secondary 
fragment.texcoord 
fragment.texcoord[n] 
fragment. fogcoord 


Outputs 


Components 


(x,y,2,1/w) 


(r,g,b,a) 
(1,g,b,a) 
(1,g,b,a) 
(s,t,,q) 
(s,t,r,q) 
(f,0,0,1) 


Description 


Window-space position, reciprocal of clip- 
space w 

Primary color 

Primary color 

Secondary color 

Texture coordinate 0 

Texture coordinate n 

Fog coordinate/distance 


Outputs are write-only registers that can be used to store the result of an instruction. Like 
input attributes, outputs are also necessarily different between low-level vertex and frag- 


ment shaders. 


Vertex Outputs 


The set of vertex output registers for the most part represents the colors and coordinates 
that will be interpolated across the primitive to which the vertex belongs and will become 
available as fragment shader input attributes. Table 20.8 lists all the low-level vertex shader 


outputs. 


TABLE 20.8 Vertex Outputs 
Output Binding 


result.position 
result.color 
result.color.primary 
result.color.secondary 
result.color.front 
result.color.front.primary 
result.color.front.secondary 
result.color.back 
result.color.back.primary 
result.color.back.secondary 
result. fogcoord 
result.pointsize 

result. texcoord 

result, texcoord[n] 


Components 


(x,y,Z,W) 
(r,g,b,a) 
(r,g,b,a) 
(r,g,b,a) 
(r,g,b,a) 
(r,g,b,a) 
(r,g,b,a) 
(r,g,b,a) 
(r,g,b,a) 
(1,9, b,a) 
(f, wien * 
(See 
(s,t,1,q) 
(s,t,1,q) 


Description 

Clip-space position 
Front-facing primary color 
Front-facing primary color 
Front-facing secondary color 
Front-facing primary color 
Front-facing primary color 
Front-facing secondary color 
Back-facing primary color 
Back-facing primary color 
Back-facing secondary color 
Fog coordinate 

Point size 

Texture coordinate 0 
Texture coordinate n 


The fog coordinate and point size outputs are scalar. Only the first component is used, and 
the others are ignored. The point size is used only during rasterization to affect the size of 
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the point primitive being generated. It does not become available as a fragment shader 
input. 


Notice that there are four color outputs from the vertex shader and only two color input 
attributes in the fragment shader. The reason is that the orientation of the primitive is 
determined during rasterization, at which point either the front-facing or back-facing 
colors are passed along to the fragment shader. 


Any output that isn’t written by the vertex shader becomes undefined, so if you then try 
to use it as an input in the fragment shader, you get garbage. Moral of the story: Make 
sure that you match up your fragment shader with a vertex shader that generates all the 
needed interpolants! 


Fragment Outputs 
Fragment shaders have only two outputs, a final color and a depth (see Table 20.9). 


TABLE 20.9 Fragment Outputs 


Output Binding Components Description 
result.color (r,g,b,a) Color 
result.depth * *0;*) Depth coordinate 


The output color is passed along to subsequent per-fragment operations, such as alpha test 
and blending, and finally is stored in the framebuffer. 


The depth output is handled a bit differently than other outputs. Whereas all other 
outputs are undefined if you don’t write them, fragment depth defaults to the depth 
produced by rasterization if you don’t write it. If you do write to the depth output, it over- 
rides the rasterization depth, and this depth is passed along to subsequent stencil and 
depth test stages. 


Aliases 


An alias isn’t actually its own type of register. It’s just a way of giving a new variable name 
to an existing register. Temporaries are limited resources, so aliases let you give meaningful 
new names to “recycled” registers. Here’s a contrived example: 


TEMP baseMap, outColor; 
ALIAS lightMap = baseMap; 


MOV outColor, fragment.color; 

TEX baseMap, fragment.texcoord[®], texture[@], 2D; 

MUL outColor, outColor, baseMap; 

# This next texture lookup puts its result in the same 
# physical temp as the last lookup, but gives it a new 
# name to make the shader more easily readable 


Input and Output Modifiers 


TEX lightMap, fragment.texcoord[1], texture[1], 2D; 
MUL outColor, outColor, lightMap; 


Addresses 

Address registers are used for relative addressing of parameter arrays. This type of address- 
ing gives you access into an array using an arbitrarily computed index. Relative addressing 
is allowed only in low-level vertex shaders, not in fragment shaders. 


Only the first component of an address register is used. The other three components 
might as well not exist; they can neither be read nor written. Before using relative address- 
ing, you have to declare your address register and then write to it with the ARL (address 
register load) instruction: 


ADDRESS myAddress; 
TEMP computedAddress, chosenOffset; 
PARAM offsets[] = { 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0 }; 


# ARL is a glorified FLR instruction that only writes to address registers 
ARL myAddress.x, computedAddress; 
MOV chosenOffset, offsets[myAddress.x]; 


Input and Output Modifiers 


A few operations can be applied to input and output registers as part of each instruction. 
They are described in the following sections. 


Input Negate 
The first operation we'll discuss is input negate. You can negate each input argument to an 
instruction by putting a minus sign in front of it: 


MOV negativeVal, -positiveVal; 


Input Swizzle 


Another modifier to input arguments is the swizzle suffix. This suffix swizzles, or 
rearranges, the components of an input register. This example takes a parameter vector 
and reverses the order of its components: 


PARAM someConstant = { 1, 2, 3, 4 }; 


# The following swizzle results in 4,3,2,1 
MUL result, result, someConstant.wzyx; 
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The swizzle can be any combination of the components x, y, z, and w, such as .2zzz, 
.xywy, or even the redundant .xyzw. It can also be a single component, where .x is equiv- 
alent to .xxxx. Low-level fragment shaders let you use the letters r, g, b, and a for your 
swizzles as well because colors are more predominant than coordinates within fragment 
shaders. .abgr is the same as .wzyx. 


For scalar instructions that operate on a single input channel (COS, EX2, EXP, LG2, LOG, POW, 
RCP, RSQ, SCS, and SIN), you are forced to use a suffix to select the single component that 
will be used: 


RCP oneOverZ, myCoord.z; 


Output Writemask 

Swizzle suffixes determine which components to make available from each input register. 
Similarly, writemask suffixes determine which output components are written and which 
remain untouched: 


MOV myResult.xyw, foo; # 3rd component stays as-is 


The same component letters can be used for writemasks as for swizzles. Vertex shaders can 
use x, y, z, and w, whereas fragment shaders can also use r, g, b, and a for their 
writemasks. This is just in the name of readability. myColor.rgb is a lot easier to under- 
stand at first glance than myColor. xyz. 


Output Clamp 

The final modifier is output clamp, also known as saturation. It clamps the result of an 
instruction to the range [0,1]. This modifier is most useful for colors, and therefore is 
available only in the low-level fragment shader. 


To do an output clamp, you just add the _SAT suffix to your fragment shader instruction, 
as follows: 


ADD myResult, primaryColor, secondaryColor; # This could overflow 
# outside [0,1] 
ADD_SAT myResult, primaryColor, secondaryColor; # Here we clamp to [0,1] 


The only instruction this doesn’t make sense for is the KIL instruction, which has no 
output. 


Note that OpenGL automatically clamps the final color and depth outputs from your frag- 
ment shader before using them in subsequent pipeline stages, so you don’t need to add 
_SAT yourself on the final writes to result.color or result.depth. The output clamp 
modifier is just there to facilitate the clamping of intermediate computations. 


Resource Consumption and Queries 


If you want to clamp a register value within a vertex shader, your best bet is to use the MIN 
and MAX instructions. This sequence can also be used in a fragment shader to clamp to an 
arbitrary range other than [0,1]: 


MIN myValue, myValue, 1; 
MAX myValue, myValue, Q; 


Resource Consumption and Queries 


OpenGL implementations have a limited number of resources available to low-level 
shaders. These resources include temporaries, parameters, instructions, and a few others. If 
you want your shader to run fast, or even run at all, you need to pay attention to these 
limits and try to minimize your resource consumption. 


Parser Limits 

The first set of limits is the parser limits. These limits dictate the maximum number of 
resources that can be present in your shader for OpenGL to even consider trying to 
compile it. If you exceed any of these limits when calling g1ProgramStringARB, your 
shader will fail to parse, an error will be thrown, and the error string will reflect which 
resource you overused. 


Table 20.10 lists each resource, the way to query its parser limit via g1GetProgramivARB, 
and the minimum number that must be supported by all implementations. Limits are 
different for vertex shaders and fragment shaders, and some limits apply only to one or 
the other. 


TABLE 20.10 Parser Resource Limit Queries 


Resource Query VS Min. FS Min. 
Instructions GL_MAX_PROGRAM_INSTRUCTIONS_ARB 128 72 
Temporaries GL_MAX_PROGRAM_TEMPORARIES_ARB 12 16 
Parameters GL_MAX_PROGRAM_PARAMETERS_ARB 96 24 
Program env GL_MAX_PROGRAM_ENV_PARAMETERS_ARB 96 24 
parameters 

Program local GL_MAX_PROGRAM_LOCAL_PARAMETERS_ARB 96 24 
parameters 

Attributes GL_MAX_PROGRAM_ATTRIBS_ARB 16 10 
Addresses GL_MAX_PROGRAM_ADDRESS_REGISTERS_ARB_ 1 n/a 
ALU instructions GL_MAX_PROGRAM_ALU_INSTRUCTIONS_ARB n/a 48 
Texture instructions | GL_MAX_PROGRAM_TEX_INSTRUCTIONS ARB n/a 24 
Texture indirections GL_MAX_PROGRAM_TEX_INDIRECTIONS ARB n/a 4 


If your shader parsed successfully, you can call glGetProgramivARB to find out how many 
of each resource was counted by the parser. Table 20.11 lists these query tokens. 
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TABLE 20.11 Parser Resource Consumption Queries 


Resource Query 

Instructions GL_PROGRAM_INSTRUCTIONS_ARB 
Temporaries GL_PROGRAM_TEMPORARIES_ARB 
Parameters GL_PROGRAM_PARAMETERS_ARB 
Attributes GL_PROGRAM_ATTRIBS_ARB 

Addresses (VS only) GL_PROGRAM_ADDRESS_REGISTERS_ARB 
ALU instructions (FS only) GL_PROGRAM_ALU_INSTRUCTIONS_ARB 
Texture instructions (FS only) GL_PROGRAM_TEX_INSTRUCTIONS_ARB 
Texture indirections (FS only) GL_PROGRAM_TEX_INDIRECTIONS_ARB 


Texture Indirections 

You may find yourself asking, “What's a texture indirection?” Or you might not ask your- 
self that question until the first time you try loading a big shader, and you get an error 
string complaining about texture indirections. This is as good a place as any to address 
this resource. 


Fixed functionality always used texture coordinate interpolants to sample from textures. 
But fragment shaders introduce the ability to use any arbitrarily computed temporary 
register as a texture coordinate. In fact, you can use the result of one texture lookup as the 
texture coordinate for another lookup. This is called a dependent lookup. 


A chain of dependent lookups is simply one dependent lookup after another, where the 
result of one lookup becomes the texture coordinate for the next lookup, repeated some 
number of times. Some hardware implementations have an internal limit on the length of 
the dependency chain that can be used within a fragment shader. This is one of the most 
common fragment shader pitfalls, and if you take a moment to familiarize yourself with 
texture indirections, you can avoid hitting the ceiling of this resource. 


The GL_ARB_fragment_program specification provides a fairly simple algorithm used by 
parsers for counting texture indirections. In the specification, see issue 24, “What is a 
texture indirection, and how is it counted?” It’s easy enough that you can run the algo- 
rithm in your head when scanning your own fragment shader text to find out where indi- 
rections are being introduced and how to eliminate unnecessary ones. 


Native Limits 

The parser limits reflect what you pass into the parser. All implementations should count 
resources exactly the same way against the parser limits. But when your shader falls within 
these parse limits and successfully parses, you enter a world where all hardware is differ- 
ent. Optimizing compilers take over from here. 


Native resource limits reflect more closely what the hardware really has to offer. For 
example, some hardware implementations might take eight native instructions to 
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perform a sine/cosine (SCS), whereas others might take just one cycle. In both cases, the 
parser counts this as just one instruction, but the native resource count varies. 


Even if, on ideal mythical hardware, all instructions consumed just one native cycle, your 
parser limits and native limits might still be different. An implementation might advertise 
twice as many resources for its parser limit than it can actually support in hardware. This 
would give an optimizer the opportunity to try to reduce the shader enough that it would 
fit within the native limits. Such optimizations include instruction rescheduling, dead 
code removal, constant folding, and temporary register collapsing. Significantly reducing a 
shader’s native resource consumption is possible, so it makes sense to give the compiler 
bigger shaders to take a crack at. 


Tables 20.12 and 20.13 list the native limit queries as well as the queries to find out the 
native consumption of a successfully compiled and optimized shader. They all are queried 
via glGetProgramivARB. 


TABLE 20.12 Native Resource Limit Queries 


Resource Query 

Instructions GL_MAX_PROGRAM_NATIVE_INSTRUCTIONS_ARB 
Temporaries GL_MAX_PROGRAM_NATIVE_TEMPORARIES_ARB 
Parameters GL_MAX_PROGRAM_NATIVE_PARAMETERS_ARB 
Attributes GL_MAX_PROGRAM_NATIVE_ATTRIBS_ARB 

Addresses (VS only) GL_MAX_PROGRAM_NATIVE_ADDRESS_REGISTERS_ARB 
ALU instructions (FS only) GL_MAX_PROGRAM_NATIVE_ALU_INSTRUCTIONS_ARB 
Texture instructions (FS only) GL_MAX_PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB 
Texture indirections (FS only) GL_MAX_PROGRAM_NATIVE_TEX_INDIRECTIONS ARB 


TABLE 20.13 Native Resource Consumption Queries 


Resource Query 

Instructions GL_PROGRAM_NATIVE_INSTRUCTIONS_ARB 
Temporaries GL_PROGRAM_NATIVE_TEMPORARIES_ ARB 
Parameters GL_PROGRAM_NATIVE_PARAMETERS_ARB 
Attributes GL_PROGRAM_NATIVE_ATTRIBS_ARB 

Addresses (VS only) GL_PROGRAM_NATIVE_ADDRESS_REGISTERS_ARB 
ALU instructions (FS only) GL_PROGRAM_NATIVE_ALU_INSTRUCTIONS_ARB 
Texture instructions (FS only) GL_PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB 
Texture indirections (FS only) GL_PROGRAM_NATIVE_TEX_INDIRECTIONS ARB 
All native limits satisfied? (0/1) GL_PROGRAM_UNDER_NATIVE_LIMITS_ARB 


0Z 


Notice the last entry in Table 20.12. If g1ProgramStringARB returns without error, you can 
then perform this single query to determine whether all resources fell within native limits. 
If the result is true, you can expect your shader to be hardware accelerated. If it is false, 
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your shader may be executed in software, which can be painfully slow. Or if you prefer, 
you can query each resource individually to get a finer-detailed perspective on which 
native resources are near or exceeding their limits. 


Other Queries 


Like everything else in OpenGL, any state you can set can also be queried. Program para- 
meters can be queried with the gl1GetProgramEnvParameter*ARB and 
glGetProgramLocalParameter*ARB commands. You can read back your whole shader text 
via glGetProgramStringARB. You can check the current vertex attributes with 
glGetVertexAttrib*ARB or the vertex attribute array pointer with 
glGetVertexAttribPointervARB. To see whether a given name represents an existing 
shader, call gl1IsProgramARB. You can find the details of all these queries in the reference 
section. 


Shader Options 


The shader grammar and behavior can be altered with options. An OPTION line appears at 
the beginning of a shader before any real instructions. G__ARB_vertex_program and 
GL_ARB_fragment_program provide the options listed in the following sections, but future 
extensions may introduce additional options. 


Position-Invariant Vertex Option 


Usually, a vertex shader is required to output to result.position. If this option is present, 
you cannot output to result.position, and instead the vertex is automatically trans- 
formed to clip space for you: 


!!ARBvp1.0 
OPTION ARB_position_invariant; 


Using this option is not only a convenience when you don’t need fancy vertex transfor- 
mation, but it also helps ensure that the transformation will be the same with or without 
vertex shaders so you don’t have to worry about precision artifacts when multipass 
rendering. 


Fog Application Fragment Options 

Each fog application fragment option is another convenience option. Fragment shaders 
subsume the fog stage and thus are responsible for performing their own fog computa- 
tions. However, if you specify one of the three fog options shown here, the work will be 
done for you, just like in fixed functionality. You just choose linear, exponential, or 
second-order exponential: 


!!ARBfp1.0 
OPTION ARB_fog_linear; 


Reference 


OPTION ARB_fog_exp; # You can't actually specify more than one of these 
OPTION ARB_fog_exp2; # in your shader or it will fail to parse! 


Precision Hint Fragment Option 

Some fragment shader hardware implementations may support multiple floating-point 
calculation and internal storage precisions that either exceed or fall short of OpenGL’s 
minimum precision requirements. You can hint to the driver whether you would prefer 
your fragment shader to be run on more or less than the default precision by using one of 
these options. Remember, this is just a hint, and some implementations simply ignore the 
hint: 


!!ARBfp1.® 
OPTION ARB_precision_hint_nicest; # Again, you can only have 
OPTION ARB_precision_hint_fastest; # one of these options 


Summary 


As you can tell by the length and density of this chapter, low-level shaders are a mix of 
rocket science and brain surgery. And we haven’t even talked about any applications yet; 
that will start in Chapter 22, “Vertex Shading: Do-It-Yourself Transform, Lighting, and 
Texgen.” Seeing these shaders in action will make them less intimidating. 


What we covered here is the mechanics of low-level shaders. You’ve been exposed to 
myriad instruction opcodes, variable types, and input and output modifiers. Finally, we 
discussed queries and shader options. Soon enough we'll put all this information to work 
for us. 


Reference 


g|BindProgramARB 


Purpose: Binds a shader. 

Include File: <glext.h> 

Syntax: 

void glBindProgramARB(GLenum target, GLuint program) ; 


Description: This function binds a low-level shader to the vertex shader or fragment 
shader target. If the shader has not been bound before, it is created. 
Subsequent changes to or queries of the target affect or return state from 
the bound shader. 
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Parameters: 

target GLenum: The type of shader being bound. It can be one of the 
following constants: 
GL_VERTEX_PROGRAM_ARB: Bind a vertex shader. 
GL_FRAGMENT_PROGRAM_ARB: Bind a fragment shader. 

program GLuint: The name of the shader to bind. 

Returns: None. 

See Also: glDeleteProgramsARB, glProgramStringARB, glGenProgramsARB 

glDeleteProgramsARB 

Purpose: Deletes one or more shaders. 

Include File: <glext.h> 

Syntax: 


void glDeleteProgramsARB(GLsizei n, const GLuint *programs) ; 


Description: This function deletes shaders. The contents are deleted, and the names 
are marked as unused. If such a buffer object is currently bound in the 
current context, all such bindings are reset to zero. If an unused shader 
name or name zero is specified for deletion, that name is silently ignored. 


Parameters: 

n GLsizei: The number of shaders to delete. 

programs GLuint *: Pointer to an array containing the names of the shaders to 
delete. 

Returns: None. 

See Also: glBindProgramARB, glProgramStringARB, glGenProgramsARB, 
glIsProgramARB 


glDisableVertexAttribArrayARB 


Purpose: Disables a vertex attribute array. 
Include File: <glext.h> 
Syntax: 


void glDisableVertexAttribArrayARB(GLuint index) ; 


Description: This function behaves like g1DisableClientState, but because the 
number of vertex attributes is unbounded, conventional vertex array flags 
can’t be used. Instead, a vertex attribute number is passed into this entry- 
point indicating which vertex attribute array to disable. 


Reference 


Parameters: 

index GLuint: The vertex attribute array number to disable. 
Returns: None. 

See Also: glEnableVertexAttribArrayARB, glVertexAttribPointerARB 


glEnableVertexAttribArrayARB 


Purpose: Enables a vertex attribute array. 
Include File: <glext.h> 
Syntax: 


void glEnableVertexAttribArrayARB(GLuint index); 


Description: This function behaves like glEnableClientState, but because the 
number of vertex attributes is unbounded, conventional vertex array flags 
can’t be used. Instead, a vertex attribute number is passed into this entry- 
point indicating which vertex attribute array to enable. 


Parameters: 

index GLuint: The vertex attribute array number to enable. 

Returns: None. 

See Also: glDeleteProgramsARB, glProgramStringARB, glGenProgramsARB 
glGenProgramsARB 

Purpose: Returns unused low-level shader names. 

Include File: <glext.h> 

Syntax: 


void glGenProgramsARB(GLsizei n, GLuint *programs) ; 


Description: This function returns unused shader names. The names can subsequently 
be bound with g1BindProgramARB. 

Parameters: 

n GLsizei: The number of low-level shader names to return. 

programs GLuint *: Pointer to an array to fill with unused shader names. 

Returns: None. 

See Also: glBindProgramARB, glProgramStringARB, glDeleteProgramsARB, 


glIsProgramARB 
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glGetProgramivARB 

Purpose: Queries shader properties. 
Include File: <glext.h> 

Syntax: 


void glGetProgramivARB(GLenum target, GLenum pname, GLint *params) ; 


Description: This function queries a property of the current low-level vertex or frag- 
ment shader. 

Parameters: 

target GLenum: The type of shader being queried. It can be one of the following 
constants: 
GL_VERTEX_PROGRAM_ARB: Queries the current vertex shader. 
GL_FRAGMENT_PROGRAM_ARB: Queries the current fragment shader. 

pname GLenum: The shader property to query. It can be one of the following 


constants: 

GL_PROGRAM_LENGTH_ARB: Length of the shader in bytes. 
GL_PROGRAM_FORMAT_ARB: Format of the shader (always ASCII). 
GL_PROGRAM_BINDING_ARB: Name of the currently bound shader. 
GL_PROGRAM_INSTRUCTIONS_ARB: Number of parsed instructions in the 
current shader. 

GL_MAX_PROGRAM_INSTRUCTIONS_ARB: Maximum parsable number of 
instructions. 

GL_PROGRAM_NATIVE_INSTRUCTIONS_ARB: Number of native instructions in 
the current shader. 


GL_MAX_PROGRAM_NATIVE_INSTRUCTIONS ARB: Maximum available native 
instructions. 

GL_PROGRAM_TEMPORARIES_ARB: Number of parsed temporaries in the 
current shader. 


GL_MAX_PROGRAM_TEMPORARIES_ARB: Maximum parsable number of tempo- 
raries. 


GL_PROGRAM_NATIVE_TEMPORARIES_ARB: Number of native temporaries in 
the current shader. 

GL_MAX_PROGRAM_NATIVE_TEMPORARIES_ARB: Maximum available native 
temporaries. 


GL_PROGRAM_PARAMETERS_ARB: Number of parsed parameters in the 
current shader. 


Reference 


GL_MAX_PROGRAM_PARAMETERS_ARB: Maximum parsable number of parame- 
ters. 

GL_PROGRAM_NATIVE_PARAMETERS_ARB: Number of native parameters in the 
current shader. 

GL_MAX_PROGRAM_NATIVE_PARAMETERS ARB: Maximum available native 
parameters. 

GL_PROGRAM_ATTRIBS_ARB: Number of parsed attributes in the current 
shader. 

GL_MAX_PROGRAM_ATTRIBS_ARB: Maximum parsable number of attributes. 
GL_PROGRAM_NATIVE_ATTRIBS_ARB: Number of native attributes in the 
current shader. 

GL_MAX_PROGRAM_NATIVE_ATTRIBS_ARB: Maximum available native attrib- 
utes. 

GL_PROGRAM_ADDRESS_REGISTERS_ARB: Number of parsed address registers 
in the current shader (vertex shader only). 
GL_MAX_PROGRAM_ADDRESS_REGISTERS_ARB: Maximum parsable number of 
address registers (vertex shader only). 
GL_PROGRAM_NATIVE_ADDRESS_REGISTERS_ARB: Number of native address 
registers in the current shader (vertex shader only). 
GL_MAX_PROGRAM_NATIVE_ADDRESS_REGISTERS_ARB: Maximum available 
native address registers (vertex shader only). 
GL_MAX_PROGRAM_LOCAL_PARAMETERS_ARB: Maximum parsable number of 
program local parameters. 

GL_MAX_PROGRAM_ENV_PARAMETERS_ARB: Maximum parsable number of 
program environment parameters. 
GL_PROGRAM_UNDER_NATIVE_LIMITS_ARB: Zero if current shader exceeds 
any native resource limit; one otherwise. 
GL_PROGRAM_ALU_INSTRUCTIONS_ARB: Number of parsed ALU instructions 
in the current shader (fragment shader only). 
GL_MAX_PROGRAM_ALU_INSTRUCTIONS_ARB: Maximum parsable number of 
ALU instructions (fragment shader only). 
GL_PROGRAM_NATIVE_ALU_INSTRUCTIONS_ ARB: Number of native ALU 
instructions in the current shader (fragment shader only). 
GL_MAX_PROGRAM_NATIVE_ALU_INSTRUCTIONS_ARB: Maximum available 
native ALU instructions (fragment shader only). 
GL_PROGRAM_TEX_INSTRUCTIONS_ARB: Number of parsed texture instruc- 
tions in the current shader (fragment shader only). 
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params 
Returns: 
See Also: 


GL_MAX_PROGRAM_TEX_INSTRUCTIONS_ARB: Maximum parsable number of 
texture instructions (fragment shader only). 


GL_PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB: Number of native texture 
instructions in the current shader (fragment shader only). 


GL_MAX_PROGRAM_NATIVE_TEX_INSTRUCTIONS_ARB: Maximum available 
native texture instructions (fragment shader only). 
GL_PROGRAM_TEX_INDIRECTIONS_ARB: Number of parsed texture indirec- 
tions in the current shader (fragment shader only). 
GL_MAX_PROGRAM_TEX_INDIRECTIONS ARB: Maximum parsable number of 
texture indirections (fragment shader only). 
GL_PROGRAM_NATIVE_TEX_INDIRECTIONS_ARB: Number of native texture 
indirections in the current shader (fragment shader only). 
GL_MAX_PROGRAM_NATIVE_TEX_INDIRECTIONS ARB: Maximum available 
native texture indirections (fragment shader only). 

GLint *: A pointer to the location where the query results are written. 
None. 

glProgramStringARB, glGetProgramStringARB 


glGetProgramEnvParameter*vARB 


Purpose: 
Include File: 
Syntax: 


Queries a program environment parameter. 
<glext.h> 


void glGetProgramEnvParameterdvARB(GLenum target, GLuint index, 


GLdouble *params) ; 


void glGetProgramEnvParameterfvARB(GLenum target, GLuint index, 


Description: 


Parameters: 
target 


GLfloat *params) ; 


This function retrieves a single environment parameter from the collec- 
tion shared by all vertex shaders or all fragment shaders. Either four 
single-precision floats or four double-precision floats are returned. 


GLenum: The type of shader whose environment parameter is being 
queried. It can be one of the following constants: 


GL_VERTEX_PROGRAM_ARB: Query a vertex shader environment parameter. 


GL_FRAGMENT_PROGRAM_ARB: Query a fragment shader environment para- 
meter. 


Reference 


index GLuint: The number of the environment parameter vector to query. 

params GLdouble*/ GLfloat*: A pointer to the location where the environment 
parameter vector is written. 

Returns: None. 

See Also: glGetProgramLocalParameter*vARB, glProgramEnvParameter*ARB 


glGetProgramLocalParameter*vARB 


Purpose: Queries a program local parameter. 
Include File: <glext.h> 
Syntax: 


void glGetProgramLocalParameterdvARB(GLenum target, GLuint index, 
GLdouble *params) ; 

void glGetProgramLocalParameterfvARB(GLenum target, GLuint index, 
GLfloat *params) ; 


Description: This function retrieves a single local parameter from the currently bound 
vertex or fragment shader. Either four single-precision floats or four 
double-precision floats are returned. 


Parameters: 

target GLenum: The type of shader whose local parameter is being queried. It can 
be one of the following constants: 
GL_VERTEX_PROGRAM_ARB: Query a local parameter from the current vertex 
shader. 
GL_FRAGMENT_PROGRAM_ARB: Query a local parameter from the current frag- 
ment shader. 

index GLuint: The number of the local parameter vector to query. 

params GLdouble*/ GLfloat*: A pointer to the location where the local parame- 
ter vector is written. 

Returns: None. 

See Also: glGetProgramEnvParameter*vARB, glProgramLocalParameter*ARB 


glGetProgramStringARB 


Purpose: Queries current shader text. 
Include File: <glext.h> 
Syntax: 


void glGetProgramStringARB(GLenum target, GLenum pname, GLvoid *string); 
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Description: This function reads back the shader text from the currently bound vertex 
or fragment shader into the application-provided pointer. The application 
should first query the length of the current shader to make sure enough 
space is available to hold the entire shader. 


Parameters: 

target GLenum: The type of shader text being queried. It can be one of the 
following constants: 
GL_VERTEX_PROGRAM_ARB: Read back the vertex shader text. 
GL_FRAGMENT_PROGRAM_ARB: Read back the fragment shader text. 

pname GLenum: The type of string to return. It must be GL_PROGRAM_STRING_ARB. 

string GLvoid *: A pointer to the location where the shader text will be stored. 

Returns: None. 

See Also: glProgramStringARB, glGetProgramivARB 


glGetVertexAttrib*vARB 


Purpose: Queries a property of a vertex attribute. 
Include File: <glext.h> 
Syntax: 


void glGetVertexAttribdvARB(GLuint index, GLenum pname, GLdouble *params) ; 
void glGetVertexAttribfvARB(GLuint index, GLenum pname, GLfloat *params) ; 
void glGetVertexAttribivARB(GLuint index, GLenum pname, GLint *params) ; 


Description: This function queries a property from the indicated numbered vertex 
attribute. 

Parameters: 

index GLuint: The number of the vertex attribute to query. 

pname GLenum: The vertex attribute property to query. It can be one of the 


following constants: 

GL_VERTEX_ATTRIB_ARRAY_ENABLED_ARB: One if the vertex attribute array 
is enabled; zero if not. 

GL_VERTEX_ATTRIB_ARRAY_SIZE_ARB: Number of components per vertex 
attribute array element. 

GL_VERTEX_ATTRIB_ARRAY_STRIDE_ARB: Stride between vertex attribute 
array elements. 

GL_VERTEX_ATTRIB_ARRAY_TYPE_ARB: Data type of vertex attribute array 
elements. 


GL_VERTEX_ATTRIB_ARRAY_NORMALIZED_ARB: One if fixed-point data is 
normalized when converted to floating-point; zero otherwise. 


params 


Returns: 
See Also: 


Reference 


GL_CURRENT_VERTEX_ATTRIB_ARB: Current vertex attribute state. 


GLdouble*/ GLfloat*/ GLint*: A pointer to the location where the query 
result will be stored. 


None. 


glVertexAttrib*ARB, glVertexAttribPointerARB, 
glGetVertexAttribPointervARB 


glGetVertexAttribPointervARB 


Purpose: 
Include File: 
Syntax: 


Queries a vertex attribute array pointer. 
<glext.h> 


void glGetVertexAttribPointervARB(GLuint index, GLenum pname, 


Description: 


GLvoid **pointer) ; 


This function gets the data pointer of the specified vertex attribute array. 


Parameters: 

index GLuint: The number of the vertex attribute array pointer being queried. 

pname GLenum: The property of the vertex attribute array being queried. It must 
be GL_VERTEX_ATTRIB_ARRAY_POINTER_ARB. 

pointer GLvoid **: A pointer to the location where the queried vertex attribute 
array pointer will be stored. 

Returns: None. 

See Also: glVertexAttribPointerARB, glGetVertexAttrib*ARB 

gllsProgramARB 

Purpose: Queries whether a name is a shader name. 

Include File: <glext.h> 

Syntax: 


GLboolean glIsProgramARB(GLuint program) ; 


Description: 
Parameters: 
program 


Returns: 


See Also: 


This function queries whether the specified name is the name of a shader. 


GLuint: The shader name to be queried. 


GLboolean: GL_TRUE is returned if a shader with this name has previously 
been bound and not yet deleted. Otherwise, GL_FALSE is returned. 


glBindProgramARB, glDeleteProgramsARB, glGenProgramsARB 
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glProgramEnvParameter*ARB 


Purpose: Sets a program environment parameter. 
Include File: <glext.h> 
Syntax: 


void glProgramEnvParameter4dARB(GLenum target, GLuint index, 
GLdouble x, GLdouble y, GlLdouble z, GLdouble w); 
void glProgramEnvParameter4dvARB(GLenum target, GLuint index, 
const GLdouble *params) ; 
void glProgramEnvParameter4fARB(GLenum target, GLuint index, 
GLfloat x, GLfloat y, GLfloat z, GLfloat w); 
void glProgramEnvParameter4fvARB(GLenum target, GLuint index, 
const GLfloat *params) ; 


Description: This function sets a single program environment parameter of the collec- 
tion shared by all vertex shaders or all fragment shaders. 

Parameters: 

target GLenum: The type of shader whose program environment parameter is 
being set. It can be one of the following constants: 
GL_VERTEX_PROGRAM_ARB: Set a vertex shader program environment para- 
meter. 
GL_FRAGMENT_PROGRAM_ARB: Set a fragment shader program environment 
parameter. 

index GLuint: The number of the program environment parameter vector 
to set. 

X,Y, Z,W GLdouble/ GLfloat: The components of the new program environment 
parameter. 

params GLdouble */ GLfloat *: A pointer to the four components of the new 
program environment parameter. 

Returns: None. 

See Also: glProgramLocalParameter*ARB, glGetProgramEnvParameter*ARB 


g!ProgramLocalParameter*ARB 


Purpose: Sets a program local parameter. 
Include File: <glext.h> 
Syntax: 


void glProgramLocalParameter4dARB(GLenum target, GLuint index, 
GLdouble x, GLdouble y, GLdouble z, GLdouble w); 
void glProgramLocalParameter4dvARB(GLenum target, GLuint index, 
const GLdouble *params) ; 


Reference 


void glProgramLocalParameter4fARB(GLenum target, GLuint index, 
GLfloat x, GLfloat y, GLfloat z, GLfloat w); 
void glProgramLocalParameter4fvARB(GLenum target, GLuint index, 
const GLfloat *params) ; 


Description: This function sets a single local parameter of the currently bound vertex 
or fragment shader. 

Parameters: 

target GLenum: The type of shader whose local parameter is being set. It can be 
one of the following constants: 
GL_VERTEX_PROGRAM_ARB: Set a local parameter of the current vertex 
shader. 
GL_FRAGMENT_PROGRAM_ARB: Set a local parameter of the current fragment 
shader. 

index GLuint: The number of the program local parameter vector to set. 

x,y, Z,W GLdouble/ GLfloat: The components of the new program local 
parameter. 

params GLdouble */ GLfloat *: A pointer to the four components of the new 
program local parameter. 

Returns: None. 

See Also: glProgramEnvParameter*ARB, glGetProgramLocalParameter*ARB 

glProgramStringARB 

Purpose: Sets the low-level shader text. 

Include File: <glext.h> 

Syntax: 


void glProgramStringARB(GLenum target, GLenum format, GLsizei len, 
const GLvoid *string); 


Description: This function sends new shader text into OpenGL, where it is parsed, 
compiled, and optimized. If successful, the new shader text replaces any 
pre-existing shader. However, if the new shader fails to parse or compile, 
the current shader, if any, remains in place. 

Parameters: 

target GLenum: The type of shader to replace with new shader text: 
GL_VERTEX_PROGRAM_ARB: Set shader text for the currently bound vertex 
shader. 
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GL_FRAGMENT_PROGRAM_ARB: Set shader text for the currently bound frag- 
ment shader. 


format GLenum: The format of the shader text, GL_PROGRAM_FORMAT_ASCII_ARB 

len GLsizei: The length of the shader text, measured in bytes, not including 
any null terminator at the end of the string. 

string GLvoid *: A pointer to the new shader text. 

Returns: None. 

See Also: g1BindProgramARB, glGenProgramsARB, glDeleteProgramsARB 

glVertexAttrib*ARB 

Purpose: Sets generic vertex attribute. 


Include File: <glext.h> 
Syntax: 


void glVertexAttrib1sARB(GLuint index, GLshort x); 
void glVertexAttrib1fARB(GLuint index, GLfloat x); 
void glVertexAttrib1dARB(GLuint index, GLdouble x); 
void glVertexAttrib2sARB(GLuint index, GLshort x, GLshort y); 
void glVertexAttrib2fARB(GLuint index, GLfloat x, GLfloat y); 
void glVertexAttrib2dARB(GLuint index, GLdouble x, GLdouble x); 
void glVertexAttrib3sARB(GLuint index, GLshort x, GLshort y, GLshort z); 
void glVertexAttrib3fARB(GLuint index, GLfloat x, GLfloat y, GLfloat z); 
void glVertexAttrib3dARB(GLuint index, GLdouble x, GLdouble x, GLdouble z); 
void glVertexAttrib4sARB(GLuint index, 

GLshort x, GLshort y, GLshort z, GLshort w); 
void glVertexAttrib4fARB(GLuint index, 

GLfloat x, GLfloat y, GLfloat z, GLfloat w); 
void glVertexAttrib4dARB(GLuint index, 

GLdouble x, GLdouble x, GLdouble z, GLdouble w); 
void glVertexAttrib4NubARB(GLuint index, 

GLubyte x, GLubyte y, GLubyte z, GLubyte w); 

void glVertexAttribisvARB(GLuint index, const GLshort *v); 
void glVertexAttribifvARB(GLuint index, const GLfloat *v); 
void glVertexAttribidvARB(GLuint index, const GLdouble *v); 
void glVertexAttrib2svARB(GLuint index, const GLshort *v); 
void glVertexAttrib2fvARB(GLuint index, const GLfloat *v); 
void glVertexAttrib2dvARB(GLuint index, const GLdouble *v); 
void glVertexAttrib3svARB(GLuint index, const GLshort *v); 
void glVertexAttrib3fvARB(GLuint index, const GLfloat *v); 
void glVertexAttrib3dvARB(GLuint index, const GLdouble *v); 
void glVertexAttrib4bvARB(GLuint index, const GLbyte *v); 


void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 
void 


Reference 


glVertexAttrib4svARB(GLuint index, const GLshort *v); 
glVertexAttrib4ivARB(GLuint index, const GLint *v); 
glVertexAttrib4ubvARB(GLuint index, const GLubyte *v); 
glVertexAttrib4usvARB(GLuint index, const GLushort *v); 
glVertexAttrib4uivARB(GLuint index, const GLuint *v); 
glVertexAttrib4fvARB(GLuint index, const GLfloat *v); 
glVertexAttrib4dvARB(GLuint index, const GLdouble *v); 
glVertexAttrib4NbvARB(GLuint index, const GLbyte *v); 
glVertexAttrib4NsvARB(GLuint index, const GLshort *v); 
glVertexAttrib4NivARB(GLuint index, const GLint *v); 
glVertexAttrib4NubvARB(GLuint index, const GLubyte *v); 
glVertexAttrib4NusvARB(GLuint index, const GLushort *v); 
glVertexAttrib4NuivARB(GLuint index, const GLuint *v); 


Description: This function sets a generic vertex attribute of the current vertex. The 


versions with N first normalize the values to the range [0,1] for unsigned 
types or [-1,1] for signed types. 


Parameters: 

index GLuint: The number of the generic vertex attribute to set. 

x, Y, Z,W all types: The components of the new generic vertex attribute. If y, z, or w 
is unspecified, those components are padded with 0, 0, and 1, respec- 
tively. 

Vv all type pointers: A pointer to the components of the new generic vertex 
attribute. 

Returns: None. 

See Also: glVertexAttribPointerARB, glGetVertexAttrib*vARB 


glVertexAttribPointerARB 


Purpose: Sets the pointer and other properties of a generic vertex attribute array. 
Include File: <glext.h> 

Syntax: 

void glVertexAttribPointerARB(GLuint index, GLint size, GLenum type, 


GLboolean normalized, GLsizei stride, const GLvoid *pointer); 


Description: This function sets the array pointer, size, type, and stride for a generic 


vertex attribute. It will optionally normalize integer type values to the 
range [0,1] for unsigned types or [-1,1] for signed types. 
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Parameters: 


index GLuint: The number of the generic vertex attribute array pointer 
being set. 


size GLint: The number of components in each element of the generic vertex 
attribute array. 


type GLenum: The type of the generic vertex attribute array data. It can be one 
of the following constants: 


GL_DOUBLE: Double-precision floating-point. 
GL_FLOAT: Single-precision floating-point. 
GL_BYTE: Signed one-byte integer. 
GL_SHORT: Signed two-byte integer. 

GL_INT: Signed four-byte integer. 

GL_UBYTE: Unsigned one-byte integer. 
GL_USHORT: Unsigned two-byte integer. 
GL_UINT: Unsigned four-byte integer. 


normalized GLboolean: GL_TRUE if the fixed-point data should be normalized; 
GL_FALSE otherwise. 


stride GLsizei: The number of bytes to skip between elements of the array. 
pointer const GLvoid *: A pointer to the generic vertex attribute array data. 
Returns: None. 

See Also: glGetVertexAttribPointervARB, glVertexAttrib*ARB 


CHAPTER 21 


High-Level Shading: The Real Slim 
Shader 


by Benjamin Lipchak 

WHAT YOU'LL LEARN IN THIS CHAPTER: 

How To Functions You'll Use 

Create shader/program objects glCreateShader0bjectARB/glCreateProgram0bjectARB 

Specify shaders and compile glShaderSourceARB/glCompileShaderARB 

Attach/detach shaders and link glAttachObjectARB/glDetachObj ectARB/glLinkProgramARB 

Switch between programs glUseProgram0bjectARB 

Specify a uniform glUniform*ARB 

Get error and warning information glGetInfoLogARB 


You could, in theory, write all your applications in assembly language. But you don’t, and 
there are good reasons for not doing so: development time efficiency, readability, main- 
tainability, and portability, to name just a few. The benefits of assembly are becoming 
scarce with today’s high-level language compilers generating code that performs as well as, 
or even outperforms, hand-written assembly. 


So then why did we bother discussing low-level shading in the preceding chapters instead 
of skipping straight to high-level shaders, based on the OpenGL Shading Language 
(GLSL)? The answer is based on availability. The ARB-standardized low-level shader exten- 
sions, covered in Chapter 20, “Low-Level Shading: Coding to the Metal,” have been avail- 
able for years and have been the only game in town. Though in development for years, no 
high-level alternative was available on OpenGL until recently. So game and application 
developers who wanted to incorporate shading capabilities embraced the low-level exten- 
sions as their only choice at the time. 


The adoption of low-level extensions was relatively rapid because these extensions 
exposed functionality not previously available. It is likely that the migration to GLSL will 
be slower because high-level shaders, for the most part, expose only equivalent functional- 
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ity, just in an easier-to-use way. Low-level shaders, on the other hand, are entrenched with 
a two-year headstart. Applications with long development cycles may take the “if it ain’t 
broke, don’t fix it” mentality, keeping low-level shaders alive and kicking for years to 
come. But in the long run, GLSL will be the tool of choice, and low-level shaders will be a 
footnote in OpenGL history. 


Managing High-Level Shaders 


The GLSL ARB extensions are quite a departure from the core OpenGL API and other 
extensions in terms of the API they introduce. No more of the Gen/Bind/Delete that 
you're used to; GLSL gets all new entrypoints. 


Shader Objects 
GLSL uses two types of objects: shader objects and program objects. The first objects we 
will look at, shader objects, are loaded with shader text and compiled. 


Creating and Deleting 

You create shader objects by calling g1CreateShaderObjectARB and passing it the type of 
shader you want, either vertex or fragment. This function returns a handle to the shader 
object used to reference it in subsequent calls: 


GLhandleARB myVertexShader = glCreateShaderObjectARB(GL_VERTEX_SHADER_ARB) ; 
GLhandleARB myFragmentShader = glCreateShaderObjectARB(GL_FRAGMENT_SHADER_ARB) ; 


Beware that object creation may fail, in which case 0 (zero) will be returned. This may 
happen if OpenGL runs out of memory resources or object handles. When you’re done 
with your shader objects, you should clean up after yourself: 


glDelete0bjectARB(myVertexShader) ; 
glDelete0bj ectARB(myFragmentShader) ; 


Some other OpenGL objects, including texture objects, unbind an object during deletion if 
it’s currently in use. GLSL objects are different. g1DeleteObjectARB simply marks the 
object for future deletion, which will occur as soon as the object is no longer being used. 


Specifying Shader Text 

A shader object’s goal is simply to accept shader text and compile it. Your shader text can 
be hard-coded as a string-literal, read from a file on disk, or generated on the fly. One way 
or another, it needs to be in a string so you can load it into your shader object: 


GLcharARB *myStringPtrs[1]; 

myStringPtrs[®] = vertexShaderText; 
glShaderSourceARB(myVertexShader, 1, myStringPtrs, NULL); 
myStringPtrs[0] = fragmentShaderText; 
glShaderSourceARB(myFragmentShader, 1, myStringPtrs, NULL); 


Managing High-Level Shaders 


glShaderSourceARB is set up to accept multiple individual strings. The second argument is 
a count that indicates how many string pointers to look for. The strings are strung 
together into a single long string before being compiled. This capability can be useful if 
you're loading reusable subroutines from a library of functions: 


GLcharARB *myStringPtrs[3]; 

myStringPtrs[@] = vsMainText; 

myStringPtrs[1] = myNoiseFuncText; 

myStringPtrs[2] myBlendFuncText; 
glShaderSourceARB(myVertexShader, 3, myStringPtrs, NULL); 


If all your strings are null-terminated, you don’t need to specify string lengths in the 
fourth argument and can pass in NULL instead. But for shader text that is not null- 
terminated, you need to provide the length; lengths do not include the null terminator 
if present. You can use —1 for strings that are null-terminated. The following code passes 
in a pointer to an array of lengths along with the array of string pointers: 


GLint fsLength = strlen(fragmentShaderText) ; 
myStringPtrs[Q] = fragmentShaderText; 
glShaderSourceARB(myFragmentShader, 1, myStringPtrs, &fsLength) ; 


Compiling Shaders 
After your shader text is loaded into a shader object, you need to compile it. Compiling 
parses your shader and makes sure there are no errors: 


glCompileShaderARB(myVertexShader) ; 
glCompileShaderARB(myFragmentShader) ; 


You can query a flag in each shader object to see whether the compile was successful. Each 
shader object also has an information log that contains error messages if the compilation 
failed. It might also contain warnings or other useful information even if your compila- 
tion was successful. These logs are primarily intended for use as a tool while you are devel- 
oping your GLSL application: 


glCompileShaderARB(myVertexShader) ; 
glGetObjectParameterivARB(myVertexShader, GL_OBJECT_COMPILE_STATUS_ARB, 
&success) ; 
if (!success) 
{ 
GLbyte infoLog[MAX_INFO_LOG_SIZE]; 
glGetInfoLogARB(myVertexShader, MAX_INFO_LOG_SIZE, NULL, infoLog); 
fprintf(stderr, “Error in vertex shader compilation! \n"); 
fprintf(stderr, "Info log: %s\n", infoLog); 
Sleep (10000) ; 
exit(Q); 
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The returned info log string is always null terminated. If you don’t want to allocate a large 

static array to store the info log, you can find out the exact size of the info log before 

querying it: 

glGetObjectParameterivARB(myVertexShader, GL_OBJECT_INFO_LOG_LENGTH_ARB, 
&infoLogSize) ; 


Program Objects 

The second type of object GLSL uses is a program object. This object acts as a container for 
shader objects, linking them together into a single executable. You can specify a GLSL 
shader for each replaceable section of the conventional OpenGL pipeline. Currently, only 
vertex and fragment stages are replaceable, but that list could be extended in the future to 
include additional stages. 


Creating and Deleting 

Program objects are created and deleted the same way as shader objects. The difference is 
that there’s only one kind of program object, so its creation entrypoint doesn’t take an 
argument: 


GLhandleARB myProgram = glCreateProgramO0bjectARB(); 


glDelete0bjectARB(myProgram) ; 


Attaching and Detaching 
A program object is a container. You need to attach your shader objects to it if you want 
GLSL instead of fixed functionality: 


glAttachObjectARB(myProgram, myVertexShader) ; 
glAttachObjectARB(myProgram, myFragmentShader) ; 


You can even attach multiple shader objects of the same type to your program object. 
Similar to loading multiple shader source strings into a single shader object, this makes it 
possible to include function libraries shared by more than one of your program objects. 


You can choose to replace only part of the pipeline with GLSL and leave the rest to fixed 
functionality. Just don’t attach shaders for the parts you want to leave alone. Or if you’re 
switching between GLSL and fixed functionality for part of the pipeline, you can detach a 
previously attached shader object. You can even detach both shaders, in which case you’re 
back to full fixed functionality: 


glDetachObjectARB(myProgram, myVertexShader) ; 
glDetachObjectARB(myProgram, myFragmentShader) ; 


Managing High-Level Shaders 


Linking Programs 

Before you can use GLSL for rendering, you have to link your program object. This process 
takes each of the previously compiled shader objects and links them into a single 
executable: 


glLinkProgramARB (myProgram) ; 


You can query a flag in the program object to see whether the link was successful. The 
object also has an information log that contains error messages if the link failed. The log 
might also contain warnings or other useful information even if your link was successful: 


glLinkProgramARB(myProgram) ; 
glGetObjectParameterivARB(myProgram, GL_OBJECT_LINK_STATUS_ARB, &success) ; 
if (!success) 
{ 
GLbyte infoLog[MAX_INFO_LOG_ SIZE]; 
glGetInfoLogARB(myProgram, MAX_INFO_LOG_SIZE, NULL, infoLog); 
fprintf(stderr, “Error in program linkage!\n"); 
fprintf(stderr, “Info log: %s\n", infoLog) ; 
Sleep (10000) ; 
exit(Q); 


Validating Programs 

If your link was successful, odds are good that your shaders will be executable when it 
comes time to render. But some things aren’t known at link time, such as the values 
assigned to texture samplers, described in subsequent sections. A sampler may be set to an 
invalid value, or multiple samplers of different types may be illegally set to the same 
value. At link time, you don’t know what the state is going to be when you render, so 
errors cannot be thrown at that time. When you validate, however, it looks at the current 
state so you can find out once and for all whether your GLSL shaders are going to execute 
when you draw that first triangle: 


glValidateProgramARB(myProgram) ; 
glGetObjectParameterivARB(myProgram, GL_OBJECT_VALIDATE_STATUS_ARB, &success) ; 
if (!success) 
{ 
GLbyte infoLog[MAX_INFO_LOG SIZE]; 
glGetInfoLogARB(myProgram, MAX_INFO_LOG SIZE, NULL, infoLog); 
fprintf(stderr, “Error in program validation! \n"); 
fprintf(stderr, “Info log: %s\n", infoLog); 
Sleep (10000) ; 
exit(0); 
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Again, if the validation fails, an explanation and possibly tips for avoiding the failure are 
included in the program object’s info log. Note that validating your program object before 
rendering with it is not a requirement, but if you do try to use a program object that 
would have failed validation, your rendering commands will fail and throw OpenGL 
errors. 


Using Programs 
Finally, you’re ready to turn on your program. Unlike other OpenGL features, GLSL mode 
is not toggled with glEnable/g1Disable: 


glUseProgram0bject(myProgram) ; 


You can use this function to enable GLSL with a particular program object and also to 
switch between different program objects. To disable GLSL and switch back to fixed func- 
tionality, you also use this function, passing in 0: 


glUseProgramO0bject(Q) ; 


You can query for the current program object handle at any time: 


currentProgObj = glGetHandleARB(GL_PROGRAM_OBJECT_ARB) ; 


Now that you know how to manage your shaders, you can focus on their contents. The 
syntax of GLSL is largely the same as that of C/C++, so you should be able to dive right in. 


Setting Up the Extensions 


Like low-level shader extensions, GLSL is not yet part of core OpenGL at the time of this 
book’s printing. Therefore, the presence of the desired extensions must be queried, and 
entrypoint function pointers must also be obtained, as in Listing 21.1. 


You must check four GLSL extensions: GL_ARB_shader_objects, GL_ARB_vertex_shader, 
GL_ARB_fragment_shader, and GL_ARB_shading_language_100. The first contains the 
shared functionality between vertex and fragment shaders. The last reflects the version of 
the OpenGL Shading Language available. Updated versions will likely be made available 
over time. 


LISTING 21.1 Checking for the Presence of OpenGL Features 


// Make sure required functionality is available! 

if (!gltIsExtSupported("GL_ARB_vertex_shader") || 
!gltIsExtSupported("GL_ARB_fragment_shader") {| 
!{gltIsExtSupported("GL_ARB_shader_objects") {|} 
!gltIsExtSupported("“GL_ARB_shading_language_100")) 


fprintf(stderr, "GLSL extensions not available!\n"); 


Variables 


LISTING 21.1 Continued 


Sleep (2000) ; 
exit (0); 


glCreateShaderObjectARB = gltGetExtensionPointer("“glCreateShaderObjectARB") ; 
glCreateProgramObjectARB = gltGetExtensionPointer("glCreateProgram0bjectARB") ; 
glAttachObjectARB = gltGetExtensionPointer("glAttachObjectARB") ; 
glDetachObjectARB = gltGetExtensionPointer("glDetachObjectARB") ; 
glDeleteObjectARB = gltGetExtensionPointer("glDeleteObjectARB") ; 
glShaderSourceARB = gltGetExtensionPointer("glShaderSourceARB") ; 
glCompileShaderARB = gltGetExtensionPointer("“glCompileShaderARB") ; 
glLinkProgramARB = gltGetExtensionPointer(“glLinkProgramARB" ) ; 
glValidateProgramARB = gltGetExtensionPointer("glValidateProgramARB" ) ; 
glUseProgramObjectARB = gltGetExtensionPointer("glUseProgramObjectARB") ; 
glGetObjectParameterivARB = gltGetExtensionPointer(“glGetObjectParameterivARB’ ) ; 
glGetInfoLogARB = gltGetExtensionPointer("glGetInfoLogARB") ; 

glUniform1fARB = gltGetExtensionPointer("glUniform1fARB") ; 
glGetUniformLocationARB = gltGetExtensionPointer("glGetUniformLocationARB") ; 


if (!glCreateShaderObjectARB |; !glCreateProgramObjectARB }} 
!glAttachObjectARB |} !glDetachObjectARB |} !glDeleteObjectARB |} 
!glShaderSourceARB || !glCompileShaderARB {| !glLinkProgramARB |} 


!glValidateProgramARB |} !glUseProgramObjectARB {} 
!glGetObjectParameterivARB {|| !glGetInfoLogARB |} 
!glUniformifARB || !glGetUniformLocationARB) 

{ 
fprintf(stderr, "Not all entrypoints were available!\n"); 
Sleep (2000) ; 
exit(Q); 

} 

Variables 


Variables and functions must be declared in advance. Your variable name can use any 
letters (case-sensitive), numbers, or an underscore, but it can’t begin with a number. Also, 
your variable cannot begin with the prefix g1_, which is reserved for built-in variables and 
functions. A list of reserved keywords available in the OpenGL Shading Language specifi- 
cation is also off-limits. 
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Basic Types 
In addition to the Boolean, integer, and floating-point types found in C, GLSL introduces 
some data types commonly used in shaders. Table 21.1 lists these basic data types. 


TABLE 21.1 Basic Data Types 


Type Description 

void A data type required for functions that don’t return a value. Functions that take 
no arguments can optionally use void as well. 

bool A Boolean variable used primarily for conditionals and loops. It can be assigned 
to keywords true and false, or any expression that evaluates to a Boolean. 

int A variable represented by a signed integer with at least 16 bits. It can be 


expressed in decimal, octal, or hexadecimal. It is primarily used for loop counters 
and array indexing. 


float A floating-point variable approximating IEEE single-precision. It can be expressed 
in scientific notation (for example, 0.0001 = 1e-4). 

bvec2 A two-component Boolean vector. 

bvec3 A three-component Boolean vector. 

bvec4 A four-component Boolean vector. 

ivec2 A two-component integer vector. 

ivec3 A three-component integer vector. 

ivec4 A four-component integer vector. 

vec2 A two-component floating-point vector. 

vec3 A three-component floating-point vector. 

vec4 A four-component floating-point vector. 

mat2 A 2x2 floating-point matrix. Matrices are accessed in column-major order. 

mat3 A 3x3 floating-point matrix. 

mat4 A 4x4 floating-point matrix. 

sampler1D A special-purpose constant used by built-in texture functions to reference a 
specific 1D texture. It can be declared only as a uniform or function argument. 

sampler2D A constant used for referencing a 2D texture. 

sampler3D A constant used for referencing a 3D texture. 

samplerCube A constant used for referencing a cube map texture. 

sampler1DShadow A constant used for referencing a 1D depth texture with shadow comparison. 

sampler2DShadow A constant used for referencing a 2D depth texture with shadow comparison. 

Structures 


Structures can be used to group basic data types into a user-defined data type. When defin- 
ing the structure, you can declare instances of the structure at the same time, or you can 
declare them later: 


Variables 


struct surface { 
float indexOfRefraction; 
float reflectivity; 
vec3 color; 
float turbulence; 
} myFirstSurf; 


surface mySecondSurf; 


You can assign one structure to another (=) or compare two structures (==, !=). For both of 
these operations, the structures must be of the same declared type. Two structures are 
considered equal if each of their member fields is component-wise equal. To access a single 
field of a structure, you use the selector (.): 


vec3 totalColor = myFirstSurf.color + mySecondSurf.color; 


Structure definitions must contain at least one member. Arrays, discussed next, may be 
included in structures, but only when a specific array size is provided. Unlike C language 
structures, GLSL does not allow bit fields. Structures within structures are allowed as long 
as the member structure is declared in advance or in place, not later in the shader: 


struct superSurface { 

vec3 points[30]; // Sized arrays are okay 

surface surf; // Okay, as surface was defined earlier 

struct velocity { // Okay, velocity struct defined in place 
float speed; 
vec3 direction; 

} velo; 

subSurface sub; // ILLEGAL!! Forward declaration 


}; 


struct subSurface { 
int id; 


}; 


Arrays 

One-dimensional arrays of any type (including structures) can be declared. You don’t need 
to declare the size of the array as long as it is always indexed with a constant integer 
expression. Otherwise, you must declare its size up front: 


vec4 lightPositions[8]; 

surface mySurfaces[ ]; 

const int numSurfaces = 5; 

surface myFiveSurfaces[numSurfaces] ; 
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You also must declare an explicit size for your array when the array is declared as a para- 
meter in a function declaration or as a member of a structure. 


Qualifiers 
Variables can be declared with an optional type qualifier. Table 21.2 lists the available 
qualifiers. 


TABLE 21.2 Type Qualifiers 


Qualifier Description 
const Constant value initialized during declaration. It is read-only during shader execution. 


It is also used with a function call argument to indicate it’s a constant that can’t be 
written within the function. 


attribute Read-only per-vertex data, available only within vertex shaders. This data comes from 
current vertex state or from vertex arrays. It must be declared globally (outside all 
functions). 

uniform Another value that remains constant during each shader execution, but unlike a 


const, a uniform’s value is not known at compile time and is initialized outside the 
shader. A uniform is shared by the currently active vertex and fragment shaders and 
must be declared globally. 


varying Outputs of the vertex shader, such as colors or texture coordinates, that correspond 
to read-only interpolated inputs of the fragment shader. They must be declared glob- 
ally. 

in A qualifier used with a function call argument to indicate it’s only an input, and any 


changes to the variable within the called function shouldn’t affect the value in the 
calling function. This is the default behavior for function arguments if no qualifier is 


present. 

out A qualifier used with a function call argument to indicate it’s only an output, so no 
value needs to be actually passed into the function. 

inout A qualifier used with a function call argument to indicate it’s both an input and an 


output. A value is passed in from the calling function, and that value is replaced by 
the called function. 


Built-in Variables 

Built-in variables allow interaction with fixed functionality. They don’t need to be 
declared before use. Tables 21.3 and 21.4 list most of the built-in variables. Refer to the 
GLSL specification for built-in uniforms and constants. 
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TABLE 21.3 Built-in Vertex Shader Variables 
Name Type Description 
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gl_Position vec4 Output for transformed vertex position that will be used by 
fixed functionality primitive assembly, clipping, and culling; all 
vertex shaders must write to this variable. 


gl_PointSize float | Output for the size of the point to be rasterized, measured in 
pixels. 

gl_ClipVertex vec4 Output for the coordinate to use for user clip-plane clipping. 

gl_Color vec4 Input attribute corresponding to per-vertex primary color. 

gl_SecondaryColor vec4 Input attribute corresponding to per-vertex secondary color. 

gl_Normal vec3 Input attribute corresponding to per-vertex normal. 

gl_Vertex vec4 Input attribute corresponding to object-space vertex position. 

gl_MultiTexCoordn vec4 Input attribute corresponding to per-vertex texture 
coordinate n. 

gl_FogCoord float Input attribute corresponding to per-vertex fog coordinate. 

gl_FrontColor vec4 Varying output for front primary color. 

gl_BackColor vec4 Varying output for back primary color. 

gl_FrontSecondaryColor vec4 Varying output for front secondary color. 

gl_BackSecondaryColor vec4 Varying output for back secondary color. 

gl_TexCoord{ } vec4 Array of varying outputs for texture coordinates. 

gl_FogFragCoord float Varying output for the fog coordinate. 


TABLE 21.4 Built-in Fragment Shader Variables 


Name Type Description 

gl_FragCoord vec4 Read-only input containing the window-space x, y, z, and 1/w. 

gl_FrontFacing bool Read-only input whose value is true if part of a front-facing 
primitive. 

gl_FragColor vec4 Output for the color to use for subsequent per-pixel operations. 

gl_FragDepth float Output for the depth to use for subsequent per-pixel opera- 
tions; if unwritten, the fixed functionality depth is used instead. 

gl_Color vec4 Interpolated read-only input containing the primary color. 

gl_SecondaryColor vec4 Interpolated read-only input containing the secondary color. 

gl_TexCoord[ } vec4 Array of interpolated read-only inputs containing texture coordi- 
nates. 

gl_FogFragCoord float Interpolated read-only input containing the fog coordinate. 

Expressions 


The following sections describe various operators and expressions found in GLSL. 
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Operators 


All the familiar C operators are available in GLSL with few exceptions. See Table 21.5 for a 
complete list. 


TABLE 21.5 Operators in Order of Precedence (From Highest to Lowest) 


Operator Description 

() Parenthetical grouping, function call or constructor 

{] Array subscript, vector or matrix selector 
Structure field selector, vector component selector 

++ +e Prefix or post-fix increment and decrement 

+= | Unary addition, subtraction, logical NOT 

bl | Multiplication and division 

+ - Binary addition and subtraction 

<> <= >=== [= Less than, greater than, less than or equal to, greater than or equal to, equal 
to, not equal to 

&& yt 44 Logical AND, OR, XOR 

es Conditional 

= += -= *= /= Assignment, arithmetic assignments 


’ Sequence 


A few operators are missing from GLSL. Because there are no pointers to worry about, you 
don’t need an address-of operator (&) or a dereference operator (*). A typecast operator is 
not needed because typecasting is not allowed. Bit-wise operators (&, |, *, ~, <<, >>, &, {=, 
“=, <<=, >>=) are reserved for future use, as are modulus operators (%, %=). 


Array Access 


Arrays are indexed using integer expressions, with the first array element at index 0. 
Shader execution is undefined if an attempt is made to access an array with an index less 
than zero or greater than or equal to the size of the array: 


vec4 myFifthColor, ambient, diffuse[6], specular[6]; 
myFifthColor = ambient + diffuse[5] + specular[5]; 


//Here's how NOT to index an array! 
vec4 mySyntaxError=ambient + diffuse[-1] + specular[6]; 


Constructors 


Constructors are special functions primarily used to initialize variables, especially of multi- 
component data types, but not arrays. They take the form of a function call with the 
name of the function being the same as the name of the type: 


vec3 myNormal = vec3(@.0, 1.0, 0.0); 


Expressions 


Constructors are not limited to declaration initializers; they can be used as expressions 
anywhere in your shader: 


greenTint = myColor + vec3(0.0, 1.0, 0.0); 


A single scalar value is assigned to all elements of a vector: 
ivec4 myColor = ivec4(255); // all 4 components get 255 
You can mix and match scalars, vectors, and matrices in your constructor, as long as you 


end up with enough components to initialize the entire data type. Any extra components 
are dropped: 


vec4 myVector1 = vec4(x, vec2(y, z), w); 
vec2 myVector2 = vec2(myVector1) ; // Zz, w are dropped 
float myFloat = float(myVector2) ; // y dropped 


Matrices are constructed in column-major order. If you provide a single scalar value, that 
value is used for the diagonal matrix elements, and all other elements are set to 0: 


// all of these are same 2x2 identity matrix 

mat2 myMatrix1 = mat2(1.0, 0.0, 0.0, 1.0); 

mat2 myMatrix2 = mat2(vec2(1.0, @.@), vec2(@.0, 1.0)); 
mat2 myMatrix3 = mat2(1.0); 


You can also use constructors to convert between the different scalar types. This is the 
only way to perform type conversions. No implicit or explicit type casts or promotions are 
possible. 


The conversion from int to float is obvious. When you are converting from float to int, 
the fractional part is dropped. When you are converting from int or float to bool, values 
of 0 or 0.0 are converted to false, and anything else is converted to true. When you are 
converting from bool to int or float, true is converted to 1 or 1.0, and false is 
converted to 0 or 0.0: 


float myFloat = 4.7; 

int myInt = int(myFloat); // myInt = 4 
bool myBool = bool(myInt); // myBool = true 
myFloat = float(myBool); // myFloat = 1 


Finally, you can initialize structures by providing arguments in the same order and of the 
same type as the structure definition: 


struct surface { 
float indexOfRefraction; 
float reflectivity; 
vec3 color; 
float turbulence; 
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}5 


surface mySurf = surface(ior, refl, vec3(red, green, blue), turb); 


Component Selectors 

Individual components of a vector can be accessed by using dot notation along with 
{x,y,Z,w}, {r,g,b,a}, or {s,t,p,q}. These different notations are useful for positions and 
normals, colors, and texture coordinates, respectively. Notice the p in place of the usual r 
texture coordinate. This component has been renamed to avoid ambiguity with the r 
color component. You cannot mix and match selectors from the different notations: 


vec3 myVector = {0.25, 0.5, 0.75}; 

float myR = myVector.r; // 0.25 

vec2 myYZ = myVector.yz; // 0.5, 0.75 

float myQ = myVector.q; // not allowed, accesses component beyond vec3 
float myRY = myVector.ry; // not allowed, mixes two notations 


You can use the component selectors to rearrange the order of components or replicate 
them: 


vec3 myZYX = myVector.zyx; // reverse order 
vec4 mySSTT = myVector.sstt; // replicate s and t twice each 


You can also use them as writemasks on the left side of an assignment to select which 
components are modified. In this case, you cannot use component selectors more than 
once: 


vec4 myColor = vec4(0.0, 1.0, 2.0, 3.0); 


myColor.x = -1.0; // -1.0, 1.0, 2.0, 3.0 
myColor.yz = vec2(-2.0, -3.0); // -1.0, -2.0, -3.0, 3.0 
myColor.wx = vec2(@.@, 1.0); // 1.0, -2.0, -3.0, 0.0 
myColor.zz = vec2(2.0, 3.0); // not allowed 


Another way to get at individual vector components or matrix components is to use array 
subscript notation. This way, you can use an arbitrarily computed integer index to access 
your vector or matrix as if it were an array. Shader execution is undefined if an attempt is 
made to access a component outside the bounds of the vector or matrix: 


float myY = myVector[1]; 
float myBug = myVector[-1]; // Don't try this! 


For matrices, providing a single array index accesses the corresponding matrix column as a 
vector. Providing a second array index accesses the corresponding vector component: 


Control Flow 


mat3 myMatrix = mat3(1.0); 
vec3 myFirstColumn = myMatrix[®]; // first column: 1.0, 0.0, 0.0 
float element21 = myMatrix[2][1]; // last column, middle row: 0.0 


Control Flow 


Low-level shaders allow only a single stream of linear execution. GLSL introduces a variety 
of familiar nonlinear flow mechanisms that reduce code size, make more complex algo- 
rithms possible, and make shaders more readable. 


Loops 

For, while, and do/while loops are all supported with the same syntax as in C/C++. Loops 
can be nested. You can use continue and break to prematurely move on to the next itera- 
tion or break out of the loop: 


for (1 = 0; 1 < numLights; 1++) 


{ 
if (!lightExists[1]) 
continue; 
color += light[1]; 
} 
while (true) 
{ 
if (lightNum < @) 
break; 
color += light[lightNum] ; 
lightNum- -; 
} 
do 
{ 


color += light[lightNum] ; 
lightNum- -; 
} while (lightNum > Q); 


if/else 
You can use if and if/else clauses to select between multiple blocks of code. These condi- 
tionals can also be nested: 


color = unlitColor; 
if (numLights > Q) 
{ 


color = 1itColor; 
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} 
if (numLights > 0) 
{ 
color = 1litColor; 
} 
else 
{ 
color = unlitColor; 
} 
discard 


Fragment shaders have a special control flow mechanism called discard. It terminates 
execution of the current fragment’s shader. All subsequent per-fragment pipeline stages are 
skipped, and the fragment is not written to the framebuffer: 


// e.g. perform an alpha test within your fragment shader 
if (color.a < 0.9) 
discard; 


Functions 

Functions are used to modularize shader code. All shaders must define a main function, 
which is the place where execution begins. The void parameter list here is optional, but 
not the void return: 


void main(void) 


{ 


} 


Functions must be either defined or declared with a prototype before use. These defini- 
tions or declarations should occur globally, outside any function. Return types are 
required, as are types for each function argument. Also, arguments can have an optional 
qualifier in, out, inout, or const (see Table 21.2): 


// function declaration 
bool isAnyComponentNegative(const vec4 v); 


// function definition 
bool isAnyComponentNegative(const vec4 v) 


{ 
if ((v.x < @.0) {| (v.y < @.0) {| 


Control Flow 


(v.Z < 0.0) || (v.w < @.)) 
return true; 

else 
return false; 


// function use 
void main() 


{ 
bool someNeg = isAnyComponentNegative(gl_ MultiTexCoord®) ; 


Structures are allowed as arguments and return types. Arrays are allowed only as argu- 
ments, in which case the declaration and definition would include the array name with 
size, whereas the function call would just use the array name without brackets or size: 


vec4 sumMyVectors(int howManyToSum, vec4 v[10]); 


void main() 


{ 
vec4 myColors[10]; 


gl_FragColor = sumMyVectors(6, myColors) ; 


You can give more than one function the same name, as long as the return type or argu- 
ment types are different. This is called function name overloading and is useful if you want 
to perform the same type of operation on, for example, different sized vectors: 


float multiplyAccumulate(float a, float b, float c) 


{ 

return (a * b) +c; // scalar definition 
} 
vec4 multiplyAccumulate(vec4 a, vec4 b, vec4 c) 
{ 

return (a * b) +c; // 4-vector definition 
} 


Recursive functions are not allowed. In other words, the same function cannot be present 
more than once in the current call stack. Some compilers may be able to catch this and 
throw an error, but in any case, shader execution will be undefined. 
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Approximately 50 built-in functions provide all sorts of useful calculations, ranging from 
simple arithmetic to trigonometry. You can consult the GLSL specification for the 
complete list and descriptions. 


Texture Lookup Functions 

Texture lookup built-in functions deserve special mention. Whereas some of the other 
built-in functions are provided as a convenience because you could code your own 
versions relatively easily, texture lookup built-in functions, listed in Table 21.6, are crucial 
to perform even the most basic texturing. 


TABLE 21.6 Texture Lookup Built-in Functions 
Prototype 


vec4 texture1D(sampler1D sampler, float coord [, float bias] ) 

vec4 texture1DProj(sampleriD sampler, vec2 coord [, float bias] ) 
vec4 texture1DProj(sampler1D sampler, vec4 coord [, float bias] ) 
vec4 texture1DLod(sampler1D sampler, float coord, float lod) 

vec4 texture1DProjLod(sampler1D sampler, vec2 coord, float lod) 

vec4 texture1DProjLod(sampler1D sampler, vec4 coord, float lod) 

vec4 texture2D(sampler2D sampler, vec2 coord [, float bias] ) 

vec4 texture2DProj(sampler2D sampler, vec3 coord [, float bias] ) 
vec4 texture2DProj(sampler2D sampler, vec4 coord [, float bias] ) 
vec4 texture2DLod(sampler2D sampler, vec2 coord, float lod) 

vec4 texture2DProjLod(sampler2D sampler, vec3 coord, float lod) 

vec4 texture2DProjLod(sampler2D sampler, vec4 coord, float lod) 

vec4 texture3D(sampler3D sampler, vec3 coord [, float bias] ) 

vec4 texture3DProj(sampler3D sampler, vec4 coord [, float bias] ) 
vec4 texture3DLod(sampler3D sampler, vec3 coord, float lod) 

vec4 texture3DProjLod(sampler3D sampler, vec4 coord, float lod) 

vec4 textureCube(samplerCube sampler, vec3 coord [, float bias] ) 
vec4 textureCubeLod(samplerCube sampler, vec3 coord, float lod) 

vec4 shadow1D(sampler1DShadow sampler, vec3 coord [, float bias] ) 
vec4 shadow2D(sampler2DShadow sampler, vec3 coord [, float bias] ) 
vec4 shadow1DProj(sampler1DShadow sampler, vec4 coord, [, float bias] ) 
vec4 shadow2DProj(sampler2DShadow sampler, vec4 coord, [, float bias] ) 
vec4 shadow1DLod(sampler1DShadow sampler, vec3 coord, float lod) 
vec4 shadow2DLod(sampler2DShadow sampler, vec3 coord, float lod) 
vec4 shadow1DProjLod(sampler1DShadow sampler, vec4 coord, float lod) 
vec4 shadow2DProjLod(sampler2DShadow sampler, vec4 coord, float lod) 


The lookup is performed on the texture of the type encoded in the function name (1D, 
2D, 3D, Cube) currently bound to the sampler represented by the sampler parameter. The 
“Proj” versions perform a projective divide on the texture coordinate before lookup. The 
divisor is the last component of the coordinate vector. 


Reference 


The “Lod” versions, available only in a vertex shader, specify the mipmap level-of-detail 
(LOD) from which to sample. The non-”Lod” versions sample from the base LOD when 
used by a vertex shader. Fragment shaders can use only the non-”Lod” versions, where the 
mipmap LOD is computed as usual based on texture coordinate derivatives. However, frag- 
ment shaders can supply an optional bias that will be added to the computed LOD. This 
bias parameter is not allowed in a vertex shader. 


The “shadow” versions perform a depth texture comparison as part of the lookup (see 
Chapter 18, “Depth Textures and Shadows”). 


Summary 


In this chapter, you learned all the nuts and bolts of the OpenGL Shader Language (GLSL). 
We discussed all the variable types, operators, and flow control mechanisms. We also 
described how to use the entrypoints for loading and compiling shader objects and linking 
and using program objects. There was a lot of ground to cover here, but we made it 
through at a record pace. 


This chapter concludes the boring lecture portion of our shader coverage. You now have a 
solid conceptual foundation for the remaining two chapters, which will provide practical 
examples of vertex and fragment shader applications using both low-level and high-level 
shader languages. The following chapters will prove much more enjoyable with all the 
textbook learning behind you. 


Reference 


glAttachObjectARB 


Purpose: Attaches an object to another container object. 

Include File: <glext.h> 

Syntax: 

void glAttachObjectARB(GLhandleARB containerObj, GLhandleARB obj); 


Description: This function attaches an object to a container object. If the first argu- 
ment is not a container object, if the second argument is already attached 
to the specified container object, or if the second object is not a type that 
can be attached to a container, an error is thrown. glLinkProgramARB 
must be called after glAttachObjectARB for the newly-attached objects to 


take effect. 

Parameters: 

containerObj GLhandleARB: The container object to which the other object is being 
attached. 


obj GLhandleArRB: The object being attached to the container object. 
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Returns: None. 
See Also: glDetachObjectARB, glLinkProgramARB, glGetAttachedObjectsARB 


glBindAttribLocationARB 


Purpose: Sets the location for a generic vertex attribute. 
Include File: <glext.h> 
Syntax: 


void glBindAttribLocationARB(GLhandleARB programObj, GLuint index, 
const GLcharARB *name) ; 


Description: This function explicitly specifies the generic vertex attribute number for 
use by the specified attribute variable. Any attributes not explicitly bound 
will be bound automatically during linking. This routine can be called at 
any time, even before a vertex shader is attached to a program object, to 
reserve generic attribute locations. Also, glLinkProgramARB must be called 
again after g1BindAttribLocationARB for the new location(s) to take 


effect. 

Parameters: 

program0bj GLhandleARB: The program object containing the vertex attribute. 

index GLuint: The number of the vertex attribute where this attribute will be 
located. 

name const GLcharARB *: The name of the attribute variable. 

Returns: None. 

See Also: glGetAttribLocationARB, glGetActiveAttribARB, glLinkProgramARB, 
glVertexAttrib*ARB, glVertexAttribPointerARB 

glCompileShaderARB 

Purpose: Compiles a shader. 

Include File: <glext.h> 

Syntax: 


void glCompileShaderARB(GLhandleARB shaderObj ) ; 


Description: This function attempts to compile the shader text previously loaded into 
the shader object. The shader object flag GL_OBUECT_COMPILE_STATUS_ARB 
is set to GL_TRUE if the compile is successful and ready for linkage; other- 
wise, it’s set to GL_FALSE. The shader object’s info log may be updated to 
include information about the compile. 


Reference 


Parameters: 

shaderObj GLhandleARB: The shader object to compile. 

Returns: None. 

See Also: glGetInfoLogARB, glShaderSourceARB, glGetObjectParameter*vARB, 


glLinkProgramARB 


glCreateProgramObjectARB 


Purpose: Creates a program object. 
Include File: <glext.h> 
Syntax: 


GLhandleARB glCreateProgram0bjectARB(GLvoid) ; 


Description: This function creates a new program object and returns its handle. 

Parameters: None. 

Returns: GLhandleArB: The handle to the new program object. 

See Also: glCreateShaderObjectARB, glDeleteObjectARB, glUseProgramObjectARB, 
glLinkProgramARB 


glCreateShaderObjectARB 


Purpose: Creates a shader object of the requested type. 
Include File: <glext.h> 
Syntax: 


GLhandleARB glCreateShaderObjectARB(GLenum shaderType) ; 


Description: This function creates a new shader object of the specified type and 
returns its handle. 

Parameters: 

shaderType GLenum: The type of shader object being created. It can be one of the 


following constants: 
GL_VERTEX_SHADER_ARB: Create a vertex shader object. 
GL_FRAGMENT_SHADER_ARB: Create a fragment shader object. 

Returns: GLhandleArB: The handle to the new shader object. 

See Also: glCreateProgramObjectARB, glDeleteObjectARB, glCompileShaderARB 
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glDeleteObjectARB 
Purpose: Deletes an object. 
Include File: <glext.h> 
Syntax: 


void glDeleteObjectARB(GLhandleARB obj); 


Description: If the specified object is not attached to any container object and is not a 
part of the current rendering state of any context, the object is deleted 
immediately. Otherwise, it is flagged for future deletion and won't be 
deleted until it’s no longer attached to any container object and no 
longer part of the current rendering state of any context. When a 
container object is deleted, all objects attached to it become detached. 


Parameters: 

obj GLhandleARB: The object to delete. 

Returns: None. 

See Also: glCreateProgramObject, glCreateShaderObjectARB, 
glGetObjectParameter*vARB, glUseProgram0bjectARB 

glDetachObjectARB 

Purpose: Detaches an object from a container object. 


Include File: <glext.h> 
Syntax: 
void glDetachObjectARB(GLhandleARB containerObj, GLhandleARB attachedObj); 


Description: This function detaches an object from a container object. If the detached 
object is flagged for deletion and not attached to any other container 
objects, it is deleted. glLinkProgramARB must be called after 
glDetachObjectARB for the newly-detached objects to take effect. 


Parameters: 

containerObj GLhandleARB: The container object from which the other object is to be 
detached. 

attached0bj GLhandleARB: The object being detached. 

Returns: None. 


See Also: glAttachObjectARB, glLinkProgramARB, glGetAttachedObjectsARB 


Reference 


glGetActiveAttribARB 


Purpose: 


Include File: 


Syntax: 


Gets information about active vertex attributes. 
<glext.h> 


void glGetActiveAttribARB(GLhandleARB programObj, GLuint index, 


Description: 


Parameters: 


program0bj 
index 
maxLength 


length 


size 


type 


name 


GLsizei maxLength, GLsizei *length, GLint *size, 
GLenum *type, GLcharARB *name) ; 


After a program object link has been attempted, this function can be 
called to find information about a particular vertex attribute variable, 
including its name, the length of its name, its size, and its type. 


GLhandleARB: The program object being queried. 
GLuint: The vertex attribute being queried. 


GLsizei: The maximum number of characters that should be returned for 
the name. 


GLsizei *: A pointer to the location where the name length is returned. 
The length includes only characters actually returned and does not 
include the null terminator. If a NULL pointer is provided, no length is 
returned. 


GLint *: A pointer to the location where the attribute size is returned. 
This size, measured in units of the returned type, is currently always 1 
but is part of the API in the event that attribute arrays become part of the 
OpenGL Shading Language at a later date. 


GLenum *: A pointer to the location where the attribute type is returned. 
The type will be one of the following constants: 


GL_FLOAT: Scalar floating-point value. 

GL_FLOAT_VEC2_ARB: Two-component floating-point vector. 
GL_FLOAT_VEC3_ARB: Three-component floating-point vector. 
GL_FLOAT_VEC4_ARB: Four-component floating-point vector. 
GL_FLOAT_MAT2_ARB: 2x2 floating-point matrix. 
GL_FLOAT_MAT3_ARB: 3x3 floating-point matrix. 
GL_FLOAT_MAT4_ARB: 4x4 floating-point matrix. 


GLcharARB *: A pointer to the location where the attribute name is 
returned as a null-terminated string. 
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See Also: 
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None. 


glGetAttribLocationARB, glBindAttribLocationARB, 
glGetVertexAttrib*vARB, glGetVertexAttribPointervARB 


glGetActiveUniformARB 


Purpose: 


Include File: 


Syntax: 


Gets information about active uniforms. 
<glext.h> 


void glGetActiveUniformARB(GLhandleARB program0bj, GLuint index, 


Description: 


Parameters: 


program0bj 
index 


maxLength 


length 


size 


type 


GLsizei maxLength, GLsizei *length, GLint *size, 
GLenum *type, GLcharARB *name) ; 


After a program object link has been attempted, this function can be 
called to find information about a particular uniform variable, including 
its name, the length of its name, its size, and its type. 


GLhandleARB: The program object being queried. 
GLuint: The uniform being queried. 


GLsizei: The maximum number of characters that should be returned for 
the name. 


GLsizei *: A pointer to the location where the name length is returned. 
The length includes only characters actually returned and does not 
include the null terminator. If a NULL pointer is provided, no length is 
returned. 


GLint *: A pointer to the location where the uniform array size is 
returned. This size is in terms of the returned type and is 1 for nonarrays. 


GLenum *: A pointer to the location where the uniform type is returned. 
The type will be one of the following constants: 


GL_FLOAT: Scalar floating-point value. 

GL_FLOAT_VEC2_ARB: Two-component floating-point vector. 
GL_FLOAT_VEC3_ARB: Three-component floating-point vector. 
GL_FLOAT_VEC4_ARB: Four-component floating-point vector. 
GL_INT: Scalar integer value. 

GL_INT_VEC2_ARB: Two-component integer vector. 
GL_INT_VEC3_ARB: Three-component integer vector. 
GL_INT_VEC4_ARB: Four-component integer vector. 
GL_BOOL_ARB: Scalar Boolean value. 

GL_BOOL_VEC2_ARB: Two-component Boolean vector. 


name 


Returns: 
See Also: 


Reference 


GL_BOOL_VEC3_ARB: Three-component Boolean vector. 
GL_BOOL_VEC4_ARB: Four-component Boolean vector. 
GL_FLOAT_MAT2_ARB: 2x2 floating-point matrix. 
GL_FLOAT_MAT3_ARB: 3x3 floating-point matrix. 
GL_FLOAT_MAT4_ARB: 4x4 floating-point matrix. 
GL_SAMPLER_1D_ARB: Handle for accessing 1D texture. 
GL_SAMPLER_2D_ARB: Handle for accessing 2D texture. 
GL_SAMPLER_3D_ARB: Handle for accessing 3D texture. 
GL_SAMPLER_CUBE_ARB: Handle for accessing cube-mapped texture. 


GL_SAMPLER_1D_SHADOW_ARB: Handle for accessing 1D depth texture with 
depth comparison. 


GL_SAMPLER_2D_SHADOW_ARB: Handle for accessing 2D depth texture with 
depth comparison. 


GLcharARB *: A pointer to the location where the uniform name is 
returned as a null-terminated string. 


None. 
glGetUniformLocationARB, glGetUniform*VARB, glUniform*ARB 


glGetAttachedObjectsARB 


Purpose: 
Include File: 
Syntax: 


Gets a list of objects attached to a container object. 
<glext.h> 


void glGetAttachedObjectsARB(GLhandleARB containerObj, GLsizei maxCount, 


Description: 


Parameters: 
container0Obj 
maxCount 


count 


obj 
Returns: 
See Also: 


GLsizei *count, GLhandleARB *obj); 


This function returns a list of all the objects contained within another 
object. Specifically, it returns all the shader objects contained within a 
program object. 


GLhandleArRB: The container object being queried. 
GLsizei: The maximum number of object handles to return. 


GLsizei *: A pointer to the location where the count is returned. The 
count includes only handles actually returned. If a NULL pointer is 
provided, no count is returned. 


GLhandleARB *: A pointer to an array of returned object handles. 
None. 
glAttachObjectARB, glDetachObjectARB, glDeleteObjectARB 


1005 


LZ 


1006 


CHAPTER 21 


High-Level Shading: The Real Slim Shader 


glGetAttribLocationARB 


Purpose: 
Include File: 
Syntax: 


Gets the location of a vertex attribute variable. 
<glext.h> 


GLint glGetAttribLocationARB(GLhandleARB program0bj, const GLcharARB *name) ; 


Description: After a program object has been successfully linked, this function returns 
the location of the vertex attribute variable with the specified name. 

Parameters: 

program0bj GLhandleARB: The program object being queried. 

name const GLcharARB *: The vertex attribute variable name, null terminated. 

Returns: GLint: The location of the vertex attribute or —-1 if no such attribute is 
active or if the name starts with the reserved prefix “gl_”. If name corre- 
sponds to an active matrix attribute, the location of the first column is 
returned. 

See Also: glGetActiveAttribARB, glBindAttribLocationARB, glLinkProgramARB, 
glVertexAttrib*ARB, glVertexAttribPointerARB 

glGetHandleARB 

Purpose: Returns an object handle. 

Include File: <glext.h> 

Syntax: 


GLhandleARB glGetHandleARB(GLenum pname) ; 


Description: This function returns the handle to an object that is part of the current 
state. 

Parameters: 

pname GLenum: The object handle from current state to return. It must be the 
constant GL_PROGRAM_OBJECT_ARB. 

Returns: GLhandleARB: The current program object or 0 if no such object is 
currently used. 

See Also: glCreateProgram0bjectARB, glUseProgramObjectARB 

glGetIinfoLogARB 

Purpose: Gets information about the last compile or link. 


Include File: 


<glext.h> 


Reference 


Syntax: 


void glGetInfoLogARB(GLhandleARB obj, GLsizei maxLength, GLsizei *length, 
GLcharARB *infoLog) ; 


Description: Each shader object has an info log that contains information about the 
most recent compile attempt by that shader object. Similarly, each 
program object has an info log that contains information about the most 
recent link or validation attempt. This function provides access to these 


logs. 

Parameters: 

obj GLhandleARB: The object whose information log is being queried. 

maxLength GLsizei: The maximum number of characters that should be returned in 
the info log. 

length GLsizei *: A pointer to the location where the length of the info log is 
returned. The length includes only characters actually returned and does 
not include the null terminator. If a NULL pointer is provided, no length 
is returned. 

infoLog GLcharARB *: A pointer to the location where the info log text is returned 
as a null-terminated string. 

Returns: None. 

See Also: glCompileShaderARB, glLinkProgramARB, glValidateProgramARB 


glGetObjectParameter*vARB 


Purpose: Gets information about the specified object. 
Include File: <glext.h> 
Syntax: 


void glGetObjectParameterfvARB(GLhandleARB obj, GLenum pname, GLfloat *params) ; 
void glGetObjectParameterivARB(GLhandleARB obj, GLenum pname, GLint *params) ; 


Description: This function queries a property of the specified program or shader 


object. 

Parameters: 

obj GLhandleArB: The object being queried. 

pname GLenum: The property being queried. It can be one of the following 
constants: 


GL_OBJECT_TYPE_ARB: Returns GL_PROGRAM_OBJECT_ARB if the object is a 
program object and GL_SHADER_OBJECT_ARB if the object is a shader 
object. 
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GL_OBJECT_SUBTYPE_ARB: Returns either GL_VERTEX_SHADER_ARB or 
GL_FRAGMENT_SHADER_ARB if the object is a shader object. 
GL_OBJECT_DELETE_STATUS_ARB: Returns 1 or 1.0 if the object’s delete flag 
is set; otherwise, 0 or 0.0 is returned. 

GL_OBJECT_COMPILE_STATUS_ARB;: Returns 1 or 1.0 if the shader object’s 
most recent compile was successful. 

GL_OBJECT_LINK_STATUS_ARB: Returns 1 or 1.0 if the program object’s 
most recent link was successful. 

GL_OBJECT_VALIDATE_STATUS_ARB: Returns 1 or 1.0 if the program object’s 
most recent validation was successful. 

GL_OBJECT_INFO_LOG_LENGTH_ARB: Returns the length in characters of 
the object’s info log, including the null terminator, or 0 if there is no 
info log. 

GL_OBJECT_ATTACHED_OBJECTS_ARB: Returns the number of shader objects 
attached to this program object. 

GL_OBJECT_ACTIVE_UNIFORMS_ARB: Returns the number of uniforms active 
in this program object. 

GL_OBJECT_ACTIVE_UNIFORM_MAX_LENGTH_ARB: Returns the length of this 
program object’s longest active uniform variable name. 
GL_OBJECT_SHADER_SOURCE_LENGTH_ARB: Returns the length of this shader 
object’s shader text, including the null terminator. 
GL_OBJECT_ACTIVE_ATTRIBUTES_ARB: Returns the number of vertex attrib- 
utes active in this program object. 


GL_OBJECT_ACTIVE_ATTRIBUTE_MAX_LENGTH_ARB: Returns the length of this 
program object’s longest active vertex attribute variable name. 


params GLfloat */GLint *: A pointer to the location where the result will be 
stored. 

Returns: None. 

See Also: glShaderSourceARB, glCompileShaderARB, glLinkProgramARB, 
glAttachObjectARB, glDetachObjectARB, glCreateShaderObjectARB, 
glCreateProgramObjectARB, glDeleteObjectARB 

glGetShaderSourceARB 

Purpose: Gets a shader object’s source text. 


Include File: 


Syntax: 


<glext.h> 


void glGetShaderSourceARB(GLhandleARB obj, GLsizei maxLength, GLsizei *length, 


GLcharARB *source) ; 


Reference 


Description: This function returns a concatenation of all the shader source text previ- 
ously supplied via g1ShaderSourceARB. 

Parameters: 

obj GLhandleArB: The shader object being queried. 

maxLength GLsizei: The maximum number of characters that should be returned. 

length GLsizei *: A pointer to the location where the length of the source text 
is returned. The length includes only characters actually returned and 
does not include the null terminator. If a NULL pointer is provided, no 
length is returned. 

source GLcharARB *: A pointer to the location where the shader source text is 
returned as a null-terminated string. 

Returns: None. 

See Also: glShaderSourceARB, glCreateShaderObjectARB, glCompileShaderARB 

glGetUniform*vARB 

Purpose: Gets the value(s) of a uniform variable. 


Include File: 
Syntax: 


<glext.h> 


void glGetUniformfvARB(GLhandleARB programObj, GLint location, 


GLfloat *params) ; 


void glGetUniformivARB(GLhandleARB program0bj, GLint location, GLint *params) ; 


Description: 


Parameters: 
program0bj 
location 
params 


Returns: 
See Also: 


If the program object has been successfully linked, and a valid uniform 
location has been provided, as by glGetUniformLocationARB, this func- 
tion returns the value or values of the uniform variable at that location. 
The number of values returned is based on the type of the uniform. Each 
element of an array variable must be queried independently. If the vari- 
able is a matrix, its data is returned in column-major order. 


GLhandleARB: The program object being queried. 
GLint: The location of the uniform variable being queried. 


GLfloat */GLint *: A pointer to the location where the uniform value(s) 
will be stored. 


None. 
glUniform*ARB, gl1GetUniformLocationARB, glGetActiveUniformARB 


1009 


LZ 


1010 


CHAPTER 21 


High-Level Shading: The Real Slim Shader 


glGetUniformLocationARB 


Purpose: 


Include File: 


Syntax: 


Gets the location of a uniform variable. 
<glext.h> 


GLint glGetUniformLocationARB(GLhandleARB programObj, const GLcharARB *name) ; 


Description: After a program object has been successfully linked, this function returns 
the location of the uniform variable with the specified name. 

Parameters: 

program0bj GLhandleARB: The program object being queried. 

name const GLcharARB *: The uniform variable name, null terminated. The 
name cannot be a structure, array of structures, or a subcomponent of a 
vector or matrix. The . and [] operators can be used to identify members 
of a structure or array. The first element of an array can be queried either 
using just the name of the array, or with [0] appended. 

Returns: GLint: The location of the uniform or —-1 if no such uniform is active or if 
the name starts with the reserved prefix "gl_". 

See Also: glGetActiveUniformARB, glLinkProgramARB, glUniform*ARB, 
glGetUniform*vARB 

glLinkProgramARB 

Purpose: Links a program object. 


Include File: 


Syntax: 


<glext.h> 


void glLinkProgramARB(GLhandleARB programObj) ; 


Description: 


Parameters: 


programObj 
Returns: 
See Also: 


This function attempts to link the previously compiled shader objects 
contained within the specified program object. The program object flag 
GL_OBJECT_LINK_STATUS_ARB is set to GL_TRUE if the link is successful and 
ready for use; otherwise, it’s set to GL_FALSE. The program object’s info 
log will be updated to include information about the link. 


GLhandleARB: The program object to link. 
None. 


glGetInfoLogARB, glGetObjectParameter*vARB, gl1CompileShaderARB, 
glUseProgramObjectARB 


Reference 


glShaderSourceARB 

Purpose: Loads source text into a shader object. 
Include File: <glext.h> 

Syntax: 


void glShaderSourceARB(GLhandleARB shaderObj, GLsizei count, 
const GLcharARB **string, const GLint *length); 


Description: This function loads a shader object with one or more strings of shader 
source text. Any pre-existing source text is replaced with the new text. 
For the new shader source to take effect, the shader object must be 
freshly compiled, and the program object(s) it is attached to must be 
freshly linked. 


Parameters: 

shaderObj GLhandleARB: The shader object whose source text is being loaded. 

count GLsizei: The number of strings to load. 

string const GLcharARB **: A pointer to an array of one or more strings, each 
representing part of the shader source text. 

length const GLint *: A pointer to an array of lengths, representing the length 
of each shader source string, excluding the null terminator. If a length is 
-1, the corresponding string is guaranteed to be null-terminated. If length 
is NULL, all strings are guaranteed to be null-terminated. 

Returns: None. 

See Also: glCompileShaderARB, glGetShaderSourceARB, glCreateShaderObjectARB 

glUniform*ARB 

Purpose: Load uniform variable values. 

Include File: <glext.h> 

Syntax: 


void glUniformifARB(GLint location, GLfloat v@); 
void glUniform2fARB(GLint location, GLfloat v@, GLfloat v7); 
void glUniform3fARB(GLint location, GLfloat v0, GLfloat v7, GLfloat v2); 
void glUniform4fARB(GLint location, GLfloat v0, GLfloat v1, 
GLfloat v2, GLfloat v3); 
void glUniform1iARB(GLint location, GLint v@); 
void glUniform2iARB(GLint location, GLint v@, GLint v7); 
void glUniform3iARB(GLint location, GLint v@, GLint v7, GLint v2); 
void glUniform4iARB(GLint location, GLint v@, GLint v7, GLint v2, GLint v3); 
void glUniform1fvARB(GLint location, GLsizei count, const GLfloat *value); 
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void glUniform2fvARB(GLint location, GLsizei count, const GLfloat *value); 

void glUniform3fvARB(GLint location, GLsizei count, const GLfloat *value); 

void glUniform4fvARB(GLint location, GLsizei count, const GLfloat *value); 

void glUniform1ivARB(GLint location, GLsizei count, const GLint *value); 

void glUniform2ivARB(GLint location, GLsizei count, const GLint *value); 

void glUniform3ivARB(GLint location, GLsizei count, const GLint *value); 

void glUniform4ivARB(GLint location, GLsizei count, const GLint *value); 

void glUniformMatrix2fvARB(GLint location, GLsizei count, GLboolean transpose, 
const GLfloat *value) ; 

void glUniformMatrix3fvARB(GLint location, GLsizei count, GLboolean transpose, 
const GLfloat *value); 

void glUniformMatrix4fvARB(GLint location, GLsizei count, GLboolean transpose, 
const GLfloat *value); 


Description: This function loads one or more values into the specified uniform vari- 
able of the currently used program object. The size and type of the func- 
tion must match the size and type of the uniform variable, except for 
Boolean type uniforms. For Boolean uniforms, either the floating-point or 
integer functions can be used, where 0.0 or 0 is converted to GL_FALSE 
and all other values are converted to GL_TRUE. If no program object is in 
use, this function will fail and generate an error. 


Parameters: 

location GLint: The location of the uniform variable to load, as returned from 
glGetUniformLocationArB. If an array, this is the starting location for 
loading array elements. 

count GLsizei: The number of array elements to load or 1 if not an array. 

transpose GLboolean: Whether or not to transpose the specified matrix elements 


before storing them in OpenGL state. If GL_TRUE, the matrix is interpreted 
as originating in row-major order, and is transposed to column-major 
order before storing. If GL_FALSE, the matrix is interpreted as being in 
column-major order already, which is the order in which GLSL operates 
on matrices. 


v0, v1, v2, v3 GLfloat / GLint: The values to load into the uniform variable. 


value GLfloat */GLint *: A pointer to the values to load into the uniform 
variable. 

Returns: None. 

See Also: glGetUniform*vARB, glGetUniformLocationARB, glGetActiveUniformARB, 


glLinkProgramARB 


Reference 


glUseProgramObjectARB 


Purpose: Sets the current program object. 
Include File: <glext.h> 
Syntax: 


void glUseProgram0bjectARB(GLhandleARB programObj ) ; 


Description: After a program object has been successfully linked, this function installs 
its executable code as part of the current rendering state. It can also be 
used to deinstall all executable code and return to a fully fixed function- 
ality pipeline. Once installed, executable code can be changed only by 
first relinking, at which point calling this function again is unnecessary. 


Parameters: 

program0bj GLhandleARB: The program object to be used or 0 to revert to fixed 
functionality. 

Returns: None. 

See Also: glLinkProgramARB, glGetHandleARB, glUniform*ARB 


glValidateProgramARB 


Purpose: Validates a program object against current state. 
Include File: <glext.h> 
Syntax: 


void glValidateProgramARB(GLhandleARB program0bj ) ; 


Description: Without taking the current state into consideration, it is impossible to 
know whether a given program object will execute when first used for 
rendering, even if it linked successfully. This function validates the speci- 
fied program object against the current OpenGL state to detect any prob- 
lems or inefficiencies. The program object flag 
GL_OBJECT_VALIDATE_STATUS_ARB is set to GL_TRUE if the validation is 
successful and the program object is guaranteed to work with the current 
state; otherwise, it’s set to GL_FALSE. The program object’s info log will be 
updated to include information about the validation. 


Parameters: 

program0bj GLhandleARB: The program object to validate. 

Returns: None. 

See Also: glGetInfoLogARB, glGetObjectParameter*vARB, glLinkProgramARB, 


glUseProgram0bj ectARB 
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CHAPTER 22 


Vertex Shading: Do-It-Yourself 
Transform, Lighting, and Texgen 


by Benjamin Lipchak 


WHAT YOU’LL LEARN IN THIS CHAPTER: 


¢ How to perform per-vertex lighting 

© How to generate texture coordinates 

¢ How to calculate per-vertex fog 

¢ How to calculate per-vertex point size 

¢ How to squash and stretch objects 

¢ How to make realistic skin with vertex blending 


This chapter is devoted to the application of vertex shaders. We covered the basic mechan- 
ics of high-level and low-level vertex shaders in the preceding two chapters, but at some 
point you have to put the textbook down and start learning by doing. Here, we introduce 
a handful of shaders that perform various real-world tasks. You are encouraged to use these 
shaders as a starting point for your own experimentation. 


Getting Your Feet Wet 


Every shader should at the very least output a clip-space position coordinate. Lighting and 
texture coordinate generation (texgen), the other operations typically performed in vertex 
shaders, may not be necessary. For example, if you’re creating a depth texture and all you 
care about are the final depth values, you wouldn’t waste instructions in your shader to 
output a color or texture coordinates. But one way or another, you always need to output 
a clip-space position for subsequent primitive assembly and rasterization to occur. 
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For your first sample shader, you'll perform the bare-bones vertex transformation that 
would occur automatically by fixed functionality if you weren’t using a vertex shader. As 
an added bonus, you’ll copy the incoming color into the outgoing color. Remember, 
anything that isn’t output remains undefined. If you want that color to be available later 
in the pipeline, you have to copy it from input to output, even if the vertex shader 
doesn’t need to change it in any way. 


For each example shader, we'll provide both a high-level and a low-level version that 
perform equivalent operations. This way, you can learn both shader languages by compari- 
son. Also, if only one of the two extensions is available on your OpenGL implementation, 
you won’t miss out completely. Figure 22.1 shows the result of the simple shaders in 
Listings 22.1 and 22.2. 


Vertex ShadersDemo | 


FIGURE 22.1 This vertex shader transforms the position to clip space and copies the vertex’s 
color from input to output. 


LISTING 22.1 Simple High-Level Vertex Shader 


// simple.vs 

// 

// Generic vertex transformation, 
// copy primary color 


void main(void) 


Getting Your Feet Wet 


LISTING 22.1 Continued 


{ 
// multiply object-space position by MVP matrix 
gl_Position = gl ModelViewProjectionMatrix * gl Vertex; 
// Copy the primary color 
gl_FrontColor = gl Color; 

} 


LISTING 22.2 Simple Low-Level Vertex Shader 
! LARBvp1. 


# simple.vp 

# 

# Generic vertex transformation, 
# copy primary color 


ATTRIB iPos = vertex.position; # input position 
ATTRIB iPrC = vertex.color.primary; # input primary color 


OUTPUT oPos = result.position; # output position 
OUTPUT oPrC = result.color.primary; output primary color 


a 


PARAM mvp[4] = { state.matrix.mvp }; # modelview * projection matrix 
TEMP clip; # temporary register 


DP4 clip.x, iPos, mvp[Q]; # multiply input position by MVP 
DP4 clip.y, iPos, mvp[1]; 
DP4 clip.z, iPos, mvp[2]; 
DP4 clip.w, iPos, mvp[3]; 


MOV oPos, clip; # output clip-space coord 
MOV oPrC, iPrc; # copy primary color in to out 
END 


Notice how much more compact and readable the high-level GLSL shader is versus the 
low-level GL_ARB_vertex_program shader. When explaining the shaders, we’ll make refer- 
ence to the GLSL version. You can compare the two to see how the high-level expressions 
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are decomposed into their low-level counterparts. For example, the multiplication of the 
object-space vertex position (gl_Vertex) by the concatenation of the modelview and 
projection matrices (g1_ModelViewProjection) to get the clip-space vertex position 
(gl_Position) is implemented in the low-level shader by a series of four dot product (DP4) 
instructions. 


Diffuse Lighting 


Diffuse lighting takes into account the orientation of a surface relative to the direction of 
incoming light. The following is the equation for diffuse lighting: 


Cay = Max{N lL, 0}*C. *C, 


N is the vertex’s unit normal, and L is the unit vector representing the direction from the 
vertex to the light source. C,,,, is the color of the surface material, and C, is the color of 
the light. C,,, is the resulting diffuse color. Because the light in the example is white, you 
can omit that term, as it would be the same as multiplying by {1,1,1,1}. Figure 22.2 shows 
the result from Listings 22.3 and 22.4, which implement the diffuse lighting equation. 


SS Vertex Shaders Demo 


FIGURE 22.2 This vertex shader computes diffuse lighting. 


Diffuse Lighting 


LISTING 22.3 Diffuse Lighting High-Level Vertex Shader 


// diffuse.vs 
// 

// Generic ve 
// diffuse li 
// white ligh 


uniform vec3 


void main(voi 
{ 
// normal 
gl_Positi 


vec3 N 
vec4 V 
vec3 L = 


// output 
float Ndo 
gl_Frontc 


rtex transformation, 
ghting based on one 
t 

lightPos0; 

d) 


MVP transform 


on = gl ModelViewProjectionMatrix * gl_ Vertex; 


normalize(gl_NormalMatrix * gl_Normal); 
gl_ModelViewMatrix * gl Vertex; 


normalize(lightPosO - 


the diffuse color 
tL = dot(N, L); 


V.xyz)3 


olor = gl_Color * vec4(max(®@.@, NdotL)); 


LISTING 22.4 Diffuse Lighting Low-Level Vertex Shader 


| LARBvp1.® 


# diffuse.vp 
# 

# Generic ver 
# diffuse lig 
# white light 


ATTRIB iPos = 
ATTRIB iPr 
ATTRIB iNrm = 


OUTPUT oPos 
OUTPUT oPrc 


tex transformation, 
hting based on one 


vertex.position; 
vertex.color.primary; 
vertex.normal; 


result.position; 
result.color.primary ; 


# input position 
# input primary color 
# input normal 


# output position 
# output primary color 


PARAM mvp[4] = { state.matrix.mvp }; # modelview * proj matrix 
{ state.matrix.modelview }; # modelview matrix 


PARAM mv[4] = 
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LISTING 22.4 Continued 


# inverse transpose of modelview matrix: 


PARAM mvIT[4] = { state.matrix.modelview.invtrans }; 


PARAM lightPos = program.local[0]; 


TEMP N, V, L, NdotL; 


DP4 
DP4 
DP4 
DP4 


DP4 
pP4 
DP4 
DP4 


SUB 
DP3 
DP3 
DP3 
DP3 
RSQ 
MUL 
DP3 
RSQ 
MUL 


DP3 
MAX 


MUL 


END 


oPos.x, iPos, mvp[Q]; 
oPos.y, iPos, mvp[1]; 
oPos.z, iPos, mvp[2]; 
oPos.w, iPos, mvp[3]; 


V.x, iPos, mv[Q]; 
V.y, iPos, mv[1]; 
V.z, iPos, mv[2]; 
V.w, iPos, mv[3]; 


L, lightPos, V; 


N.x, iNrm, mvIT[0]; 
N.y, iNrm, mvIT[1]; 
N.z, iNrm, mvIT[2]; 


N.w, N, N; 
N.w, N.w; 
N, N, N.w; 


Lew; cy G5 
LW, ews 


by ks Lewy 


NdotL, N, L; 
NdotL, NdotL, 0.0; 


oPrC, iPrC, NdotL; 


# 


light pos in eye space 
temporary registers 


xform input pos by MVP 


xform input pos by MV 


vertex to light vector 


xform norm to eye space 


normalize normal 


normalize light vector 


diffuse color 


After computing the clip-space position as you did in the “simple” shader, the “diffuse” 
shader proceeds to transform the vertex position to eye space, too. All the lighting calcula- 
tions are performed in eye space, so you need to transform the normal vector from object 


Specular Lighting 


space to eye space as well. GLSL provides the g1_NormalMatrix built-in uniform matrix as 
a convenience for this purpose. It is simply the inverse transpose of the modelview 
matrix’s upper-left 3x3 elements. The last vector you need to compute is the light vector, 
which is the direction from the vertex position to the light position, so you just subtract 
one from the other. 


Both the normal and the light vectors must be unit vectors, so you normalize them before 
continuing. GLSL supplies a built-in function to perform this common task, but in the 
low-level shader, you have to do the normalization manually. Turning an arbitrary vector 
into a unit vector is reasonably simple. You have to scale the vector components by the 
inverse of the vector’s length. A dot product operation (DP3) of the vector against itself 
returns the vector’s length squared. A reciprocal square root operation (RSQ) turns that 
length squared into the inverse length scale factor. Then you just multiply (MUL) that scale 
factor by the original vector components to yield the unit vector. 


The dot product of the two unit vectors, N and L, will be in the range [-1,1]. But because 
you're interested in the amount of diffuse lighting bouncing off the surface, having a 
negative contribution doesn’t make sense. This is why you clamp the result of the dot 
product to the range [0,1] by using the max (GLSL) or MAX (low-level) operations. The 
diffuse lighting contribution can then be multiplied by the vertex’s diffuse material color 
to obtain the final lit color. 


Specular Lighting 


Specular lighting also takes into account the orientation of a surface relative to the direc- 
tion of incoming light. The following is the equation for specular lighting: 


C,.= Max{N * H, 0)4S,* C.. * C, 


H is the unit vector representing the direction halfway between the light vector and the 
view vector, known as the half-angle vector. S.., is the specular exponent, controlling the 
tightness of the specular highlight. C,,.. is the resulting specular color. N, C,,,,, and C,, are 
the same as for diffuse lighting. Because the light in the example is white, you can again 
omit that term. Figure 22.3 illustrates the output of Listings 22.5 and 22.6, which imple- 
ment both diffuse and specular lighting equations. 


LISTING 22.5 Diffuse and Specular Lighting High-Level Vertex Shader 


// specular.vs 

// 

// Generic vertex transformation, 
// diffuse and specular lighting 
// based on one white light 


uniform vec3 lightPosQ; 
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LISTING 22.5 Continued 
void main(void) 
{ 

// normal MVP transform 


gl_Position = gl ModelViewProjectionMatrix * gl Vertex; 


vec3 N = normalize(gl_NormalMatrix * gl Normal); 
vec4 V = gl ModelViewMatrix * gl Vertex; 

vec3 L = normalize(lightPos® - V.xyz); 

vec3 H = normalize(L + vec3(@.0, 0.0, 1.0)); 
const float specularExp = 128.0; 


// calculate diffuse lighting 
float NdotL = dot(N, L); 
vec4 diffuse = gl Color * vec4(max(®.®, NdotL)); 


// calculate specular lighting 
float NdotH = dot(N, H); 
vec4 specular = vec4(pow(max(@.0@, NdotH), specularExp) ); 


// sum the diffuse and specular components 
gl_FrontColor = diffuse + specular; 


Vertex Shaders Demo 


FIGURE 22.3 This vertex shader computes diffuse and specular lighting. 


Specular Lighting 


LISTING 22.6 Diffuse and Specular Lighting Low-Level Vertex Shader 


! LARBvp1.0 


# specular.vp 

# 

# Generic vertex transformation, 
# diffuse and specular lighting 
# based on one white light 


ATTRIB iPos = vertex.position; 
ATTRIB iPrC = vertex.color.primary; 
ATTRIB iNrm = vertex.normal; 


OUTPUT oPos 
OUTPUT oPrC 


result.position; 
result.color.primary; 


PARAM mvp[4] = { state.matrix.mvp }; 
PARAM mv[4] = 
# inverse transpose of modelview matrix: 


# 


{ state.matrix.modelview }; # 


input position 
input primary color 
input normal 


output position 
output primary color 


modelview * proj matrix 
modelview matrix 


PARAM mvIT[4] = { state.matrix.modelview.invtrans }; 


PARAM lightPos = program.local[Q]; 


TEMP N, V, L, H, NdotL, NdotH; 
TEMP diffuse, specular; 


DP4 oPos.x, 
DP4 oPos.y, 
DP4 oPos.z, 
DP4 oPos.w, 


iPos, 
iPos, 
iPos, 
iPos, 


mvp[0]; 
mvp[1]; 
mvp[2]; 
mvp[3]; 


DP4 V.x, 
DP4 V.y, 
DP4 V.z, 
DP4 V.w, 


iPos, 
iPos, 
iPos, 
iPos, 


mv[]; 
mv[1]; 
mv[2]; 
mv[3]; 


SUB L, lightPos, V; 
DP3 N.x, iNrm, mvIT[Q]; 


DP3 N.y, iNrm, mvIT[1]; 
DP3 N.z, iNrm, mvIT[2]; 


# 


light pos in eye space 


temporary registers 


xform input pos by MVP 


xform input pos by MV 


vertex to light vector 


xform norm to eye space 
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LISTING 22.6 Continued 


DP3 N.w, N, N: # normalize normal 
RSQ N.w, N.w; 
MUL N, N, N.w; 


DPSAL EW, ey, Ly # normalize light vector 
RSQ L.w, L.w; 
MUL L, L, L.w; 


ADD H.xyz, L, {@, @, 1}; 


DP3 H.w, H, H; # normalize half-angle 
RSQ H.w, H.w; 

MUL H, H, H.w; 

DP3 NdotL, N, L; #N ok 


MAX NdotL, NdotL, 0.0; 
MUL diffuse, iPrC, NdotL; 


DP3 NdotH, N, H; #N-:+H 

MAX NdotH, NdotH, 0.0; 

POW specular, NdotH.x, 128.0.x; # 128 is specular exponent 
ADD oPrC, diffuse, specular; # sum the colors 

END 


The light position is a constant vector passed into the shader from the application. This 
allows you to easily change the light position interactively without having to alter the 
shader. You can do this using the left- and right-arrow keys while running the 
VertexShaders example. 


We used a hard-coded constant specular exponent of 128, which provides a nice, tight 
specular highlight. You can experiment with different values to find one you may prefer. 
Notice in the low-level shader how we supply the exponent as 128.0.x. We supplied it this 
way because a scalar value is expected, and the low-level grammar is not smart enough to 
realize that we’re providing a scalar constant, so we have to provide the redundant suffix 


anyway. 


Improved Specular Lighting 


Specular highlights change rapidly over the surface of an object. Trying to compute them 
per-vertex and then interpolating the result across a triangle gives relatively poor results. 
Instead of a nice circular highlight, you end up with a muddy polygonal-shaped highlight. 


Improved Specular Lighting 


One way you can improve the situation is to separate the diffuse lighting result from the 
specular lighting result, outputting one as the vertex’s primary color and the other as the 
secondary color. By adding the diffuse and specular colors together, you effectively satu- 
rate the color (that is, exceed a value of 1.0) wherever a specular highlight appears. If you 
try to interpolate the sum of these colors, the saturation will more broadly affect the 
entire triangle. However, if you interpolate the two colors separately and then sum them 
per fragment, the saturation will occur only where desired, cleaning up some of the 
muddiness. This sum per fragment is achieved by simply enabling GL_COLOR_SUM. Here is 
the altered GLSL code for separating the two lit colors: 


// put diffuse into primary color 
float NdotL = dot(N, L); 
gl_FrontColor = gl_ Color * vec4(max(®@.®, NdotL)); 


// put specular into secondary color 
float NdotH = dot(N, H); 
gl_FrontSecondaryColor = vec4(pow(max(@.@, NdotH), specularExp)); 


The altered low-level vertex shader code is as follows: 


OUTPUT oPrC = result.color.primary; # output primary color 
QUTPUT oScC = result.color.secondary; # output secondary color 
DP3 NdotL, N, L; #N.L 

MAX NdotL, NdotL, 0.0; 

MUL oPrC, iPrC, NdotL; # diffuse goes in primary 
DP3 NdotH, N, H; #N +H 

MAX NdotH, NdotH, 0.0; 

POW oScC, NdotH.x, 128.0.x; # spec goes in secondary 


Separating the colors improves things a bit, but the root of the problem is the specular 
exponent. By raising the specular coefficient to a power, you have a value that wants to 
change much more rapidly than per-vertex interpolation allows. In fact, if your geometry 
is not tessellated finely enough, you may lose a specular highlight altogether. 


An effective way to avoid this problem is to output just the specular coefficient (N ¢ H), 
but wait and raise it to a power per fragment. This way, you can safely interpolate the 
more slowly changing (N ¢ H). You’re not employing fragment shaders yet, so how do you 
perform this power computation per fragment? All you have to do is set up a 1D texture 
with a table of s!*8 values and send (N ¢ H) out of the vertex shader on a texture coordi- 
nate. This is considered custom texgen. Then you will use fixed functionality texture envi- 
ronment to add the specular color from the texture lookup to the interpolated diffuse 
color from the vertex shader. 
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The following is the GLSL code, again altered from the original specular lighting shader: 


// put diffuse lighting result in primary color 
float NdotL = dot(N, L); 
gl_FrontColor = gl Color * vec4(max(@.®@, NdotL)); 


// copy (N.H)*8-7 into texcoord 
float NdotH = max(@.0, (dot(N, H) * 8.0) - 7.0); 
gl_TexCoord[®] = vec4(NdotH, 0.0, 0.0, 1.0); 


The altered low-level shader code is as follows: 


OUTPUT oPrC = result.color.primary; # output primary color 
OUTPUT oTxC = result.texcoord[Q]; # output texcoord 0 
DP3 NdotL, N, L; #N.L 


MAX NdotL, NdotL, 0.0; 
MUL oPrC, iPrC, NdotL; 


a 


output diffuse 


DP3 NdotH, N, H; #N:H 

MAD NdotH.x, NdotH, 8.0, {-7.0}; # (N° H) * 8-7 

MOV oTxC, {@.0, 0.0, 0.0, 1.0}; # init other components 
MAX oTxC.x, NdotH, 0.0; # toss into texcoord 0 


Here, the (N ¢ H) has been clamped to the range [0,1]. But if you try raising most of that 
range to the power of 128, you'll get results so close to zero that they will correspond to 
texel values of zero. Only the upper 1/8 of (N ¢ H) values will begin mapping to measur- 
able texel values. To make economical use of the 1D texture, you can focus in on this 
upper 1/8 and fill the entire texture with values from this range, improving the resulting 
precision. This requires that you scale (N ¢ H) by 8 and bias by —7 so that [0,1] maps to 
[-7,1]. By using the GL_CLAMP_TO_EDGE wrap mode, values in the range [-7,0] will be 
clamped to 0. Values in the range of interest, [0,1], will receive texel values between 
(7/8)!8 and 1. 


The specular contribution resulting from the texture lookup is added to the diffuse color 
output from the vertex shader using the GL_ADD texture environment function. 


Figure 22.4 compares the three specular shaders to show the differences in quality. An 
even more precise method would be to output only the normal vector from the vertex 
shader and to encode a cube map texture so that at every N coordinate the resulting texel 
value is (N * H)'**. We’ve left this as an exercise for you. 


Improved Specular Lighting 


“specular” shader “sepspec” shader “texspec” shader 


FIGURE 22.4 The per-vertex specular highlight is improved by using separate specular or a 
specular exponent texture. 


Now that you have a decent specular highlight, you can get a little fancier and take the 
one white light and replicate it into three colored lights. This activity involves performing 
the same computations, except now you have three different light positions and you have 
to take the light color into consideration. 


As has been the case with all the lighting shaders, you can change the light positions in 
the sample by using the left- and right-arrow keys. Figure 22.5 shows the three lights in 
action, produced by Listings 22.7 and 22.8. 


2 Vertex Shaders Demo 


FIGURE 22.5 Three lights are better than one, though it’s hard to tell in black and white. 
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LISTING 22.7. Three Colored Lights High-Level Vertex Shader 


// 3lights.vs 

// 

// Generic vertex transformation, 
// 3 colored lights 


uniform vec3 lightPosQ; 
uniform vec3 lightPos1; 
uniform vec3 lightPos2; 


varying vec4 gl_TexCoord[4]; 


void main(void) 
{ 
// normal MVP transform 
gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex; 


vec3 N = normalize(gl_NormalMatrix * gl Normal); 
vec4 V = gl ModelViewMatrix * gl Vertex; 


// Light colors 

vec4 lightCol[3]; 

lightCol[@] = vec4(1.0, 0.25, 0.25, 1.0); 
lightCol[1] = vec4(@.25, 1.0, 0.25, 1.0); 
lightCol[2] = vec4(0.25, 0.25, 1.0, 1.0); 


// Light vectors 
vec3. L[3], H[3]; 


L[@] = normalize(lightPos® - V.xyz); 
L[1] = normalize(lightPos1 - V.xyz); 
L[2] = normalize(lightPos2 - V.xyz); 


gl_FrontColor = vec4(0.0); 


for (int) i = 0; TAs.Syeieh) 
{ 
// Half-angles 
H[i] = normalize(L[i] + vec3(0.0, 0.0, 1.@)); 


// Accumulate the diffuse contributions 
gl_FrontColor += gl Color * lightCol[i] * 
vec4(max(®@.@, dot(N, L[i]))); 


Improved Specular Lighting 


LISTING 22.7 Continued 
// Put N.H specular coefficients into texcoords 
gl_TexCoord[1+i] = vec4(max(@.@, dot(N, H[i]) * 8.0 - 7.0), 
@.0, 0.0, 1.0); 


LISTING 22.8 Three Colored Lights Low-Level Vertex Shader 
! LARBvp1. 


# 3lights.vp 

# 

# Generic vertex transformation, 
# 3 colored lights 


ATTRIB iPos = vertex.position; # input position 
ATTRIB iPrC = vertex.color.primary; # input primary color 
ATTRIB iNrm = vertex.normal; # input normal 


OUTPUT oPos = result.position; # output position 
OUTPUT oPrC = result.color.primary; # output primary color 
OUTPUT oTC® = result.texcoord[1]; # output texcoord 1 
OUTPUT oTC1 = result.texcoord[2]; # output texcoord 2 
OUTPUT oTC2 = result.texcoord[3]; # output texcoord 3 
PARAM mvp[4] = { state.matrix.mvp }; # modelview * proj mat 
PARAM mv[4] = { state.matrix.modelview }; # modelview matrix 


# inverse transpose of modelview matrix: 
PARAM mvIT[4] = { state.matrix.modelview.invtrans }; 


PARAM lightCol® 


{ 1.0, 0.25; 0.25, 1.0 }; 
PARAM lightCol1 = { 0.25, 1.0, 0.25, 1.0 }; # light 1 color 
PARAM lightCol2 = { 0.25, 0.25, 1.0, 1.0 }; # light 2 color 


# light ® color 

# 

# 
PARAM lightPos® = program.local[Q]; # light pos @ eye space 

# 

= 


PARAM lightPos1 = program.local[1]; light pos 1 eye space 
PARAM lightPos2 = program.local[2]; light pos 2 eye space 


TEMP N, V, L, H, NdotL, NdotH, finalColor; # temporary registers 
ALIAS diffuse = NdotL; 
ALIAS specular = NdotH; 
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LISTING 22.8 Continued 


DP4 
DP4 
DP4 
DP4 


DP4 
DP4 
DP4 
DP4 


DP3 
DP3 
DP3 


DP3 
RSQ 
MUL 


oPos.x, iPos, mvp[Q]; 
oPos.y, iPos, mvp[1]; 
oPos.z, iPos, mvp[2]; 
oPos.w, iPos, mvp[3]; 


-X, iPos, 
iPos, 
«Z, iPos, 
.wW, iPos, 


— <= = 
< 


N.x, iNrm, 
N.y, iNrm, 
N.z, iNrm, 


# LIGHT 0 
SUB L, lightPosd, V; 


DP3 
RSQ 
MUL 


ADD 


DP3 
RSQ 
MUL 


DP3 
MAX 
MUL 


# priCol * lightCol® * N.LO 
MUL finalColor, diffuse, lightColQ; 


LW, Gyals 
L.w, L.w; 
Ly. Ls, Lew; 


mv [0]; 
mv(1]; 
mv[2]; 
mv[3]; 


mvIT[Q]; 
mvIT[1]; 
mvIT[2]; 


H.xyz, L, {@, @, 1}; 


H.w, H, H; 
H.w, H.w; 
H, H, H.w; 


NdotL, N, L; 
NdotL, NdotL, 0.0; 
diffuse, iPrC, NdotL; 


DP3 NdotH, N, H; 
MAX NdotH, NdotH, 0.0; 


MOV OTC, {0.0, 0.0, 0.0, 1.0}; 
MAD oTC@.x, NdotH, 8, {-7}; 


xform input pos by MVP 


xform input pos by MV 


xform norm to eye space 


normalize normal 


vertex to light vector 


normalize light vector 


normalize half -angle 


N . LO 


priCol * N.LO 


NdotH * 8 - 7 to tc 0 


LISTING 22.8 Continued 


Improved Specular Lighting 


# LIGHT 1 
SUB L, lightPos1, V; 


DPS -L.w, “L;L; 
RSQ L.w, L.w; 
MUL L, L, L.w; 


ADD Huxyz,. L,. £0, @,. 1}; 
DP3 H.w, H, H; 

RSQ H.w, H.w; 

MUL H, H, H.w; 

DP3 NdotL, N, L; 

MAX NdotL, NdotL, 0.0; 
MUL diffuse, iPrC, NdotL; 


# priCol * lightCol@ * N.L1 


# vertex to light vector 


# normalize light vector 


# normalize half -angle 


#N. L1 


# priCol * N.L1 


MAD finalColor, diffuse, lightCol1, finalColor; 


DP3 NdotH, N, H; 

MAX NdotH, NdotH, 0.0; 

MOV oTC1, {0.0, 0.0, 0.0, 1.0}; 
MAD oTC1.x, NdotH, 8, {-7}; 


# LIGHT 2 
SUB L, lightPos2, V; 


DPS 'L.w, L, L3 
RSQ L.w, L.w; 
MUL L, L, L.w; 


ADD H.xyz, L, {0, 0, 1}; 


DP3 H.w, H, H; 
RSQ H.w, H.w; 
MUL H, H, H.w; 


DP3 NdotL, N, L; 
MAX NdotL, NdotL, 0.0; 
MUL diffuse, iPrC, NdotL; 


#N-: H1 


# NdotH * 8 - 7 to tc 1 


# vertex to light vector 


# normalize light vector 


# normalize half-angle 


#N. L2 


# priCol * N.L2 
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LISTING 22.8 Continued 


# priCol * lightCol@ * N.L2 
MAD oPrC, diffuse, lightCol2, finalColor; 


DP3 NdotH, N, H; #N + H2 

MAX NdotH, NdotH, 0.0; 

MOV oTC2, {0.0, 0.0, 0.0, 1.0}; 

MAD oTC2.x, NdotH, 8, {-7}; # NdotH * 8 - 7 to te 2 


END 


Interesting to note in this sample is the use of a loop in the GLSL version. Loops are not 
available in low-level shaders, so we've “unrolled” the loops into a linear sequence; conse- 
quently, the code that would be in the loop is replicated three times, once for each light. 
Even though GLSL permits them, some OpenGL implementations may not support loops 
in hardware anyway. So if your shader is running really slow, it may be emulating your 
shader execution in software. Unrolling the loop in your GLSL shader could alleviate the 
problem, but at the expense of making your code less readable. 


Per-Vertex Fog 


Though fog is specified as a per-fragment rasterization stage that follows texturing, often 
implementations perform most of the necessary computation per-vertex and then interpo- 
late the results across the primitive. This shortcut is sanctioned by the OpenGL specifica- 
tion because it improves performance with very little loss of image fidelity. The following 
is the equation for a second-order exponential fog factor, which controls the blending 
between the fog color and the unfogged fragment color: 


ff = e(-(d*fc)*) 


In this equation, ff is the computed fog factor. d is the density constant that controls the 
“thickness” of the fog. fc is the fog coordinate, which is usually the distance from the 
vertex to the eye, or is approximated by the absolute value of the vertex position’s Z 
component in eye space. In this chapter’s sample shaders, you'll compute the actual 
distance, not an approximation. 


In the first sample fog shader, you’ll compute only the fog coordinate and leave it to fixed 
functionality to compute the fog factor and perform the blend. In the second sample, 
you'll compute the fog factor yourself within the vertex shader and also perform the 
blending per-vertex. Performing all these operations per-vertex instead of per-fragment is 
more efficient and provides acceptable results for most uses. Figure 22.6 illustrates the 
fogged scene, which is nearly identical for the two sample fog shaders in Listings 22.9 and 
22.10. 


3 Vertex Shaders Demo 


FIGURE 22.6 Applying per-vertex fog using a vertex shader. 


LISTING 22.9 Fog Coordinate Generating High-Level Vertex Shader 


// fogcoord.vs 

// 

// Generic vertex transformation, 
// diffuse and specular lighting, 
// per-vertex fogcoord 


uniform vec3 lightPos®; 


void main(void) 
{ 
// normal MVP transform 
gl_Position = gl_ModelViewProjectionMatrix * gl Vertex; 


vec3 N = normalize(gl_NormalMatrix * gl_Normal) ; 
vec4 V = gl ModelViewMatrix * gl_ Vertex; 

vec3 L = normalize(lightPos® - V.xyz); 

vec3 H = normalize(L + vec3(0.0, 0.0, 1.0)); 
const float specularExp = 128.0; 


Per-Vertex Fog 
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LISTING 22.9 Continued 


// calculate diffuse lighting 
float NdotL = dot(N, L); 
vec4 diffuse =.gl Color * vec4(max(®.@, NdotL)); 


// calculate specular lighting 
float NdotH = dot(N, H); 
vec4 specular = vec4(pow(max(@.0, NdotH), specularExp)) ; 


// calculate fog coordinate: distance from eye 
gl_FogFragCoord = length(V); 


// sum the diffuse and specular components 
gl_FrontColor = diffuse + specular; 


LISTING 22.10 Fog Coordinate Generating Low-Level Vertex Shader 
! !ARBvp1.0 


# fogcoord.vs 

# 

# Generic vertex transformation, 
# diffuse and specular lighting, 
# per-vertex fogcoord 


ATTRIB iPos = vertex.position; # input position 

ATTRIB iPrC = vertex.color.primary; # input primary color 
ATTRIB iNrm = vertex.normal; # input normal 

OUTPUT oPos = result.position; # output position 

QUTPUT oPrC = result.color.primary; # output primary color 
OUTPUT oFgC = result.fogcoord; # output fog coordinate 
PARAM mvp[4] = { state.matrix.mvp }; # modelview * proj matrix 


PARAM mv[4] = { state.matrix.modelview }; # modelview matrix 
# inverse transpose of modelview matrix: 
PARAM mvIT[4] = { state.matrix.modelview.invtrans }; 


PARAM lightPos = program.local[Q]; # light pos in eye space 
PARAM density = program.local[1]; # fog density 
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LISTING 22.9 Continued 


TEMP N, V, L, H, NdotL, NdotH; # temporary registers 
TEMP diffuse, specular, fogCoord; 


DP4 oPos.x, iPos, mvp[Q]; # xform input pos by MVP 
DP4 oPos.y, iPos, mvp[1]; 
DP4 oPos.z, iPos, mvp[2]; 
DP4 oPos.w, iPos, mvp[3]; 


CZ 


DP4 V.x, iPos, mv[Q]; # xform input pos by MV 
DP4 V.y, iPos, mv[1]; 
DP4 V.z, iPos, mv[2]; 
DP4 V.w, iPos, mv[3]; 


SUB L, lightPos, V; # vertex to light vector 


DP3 N.x, iNrm, mvIT[Q]; # xform norm to eye space 
DP3 N.y, iNrm, mvIT[1]; 
DP3 N.z, iNrm, mvIT[2]; 


DP3 N.w, N, Nj; # normalize normal 
RSQ N.w, N.w; 
MUL N, N, N.w; 


DPS Ew, bE; # normalize light vector 
RSQ L.w, L.w; 
MUL L, L, L.w; 


ADD H.xyz, L, {0, @, 1}; 


DP3 H.w, H, H; # normalize half-angle 
RSQ H.w, H.w; 

MUL H, H, H.w; 

DP3 NdotL, N, L; SNE IE 


MAX NdotL, NdotL, 0.0; 
MUL diffuse, iPrC, NdotL; 


DP3 NdotH, N, H; #N-:H 
MAX NdotH, NdotH, 2.0; 
POW specular, NdotH.x, 128.0.x; # 128 is specular exponent 
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LISTING 22.9 Continued 


ADD oPrC, diffuse, specular; # sum the colors 


DP4 fogCoord.x, V, V; # fogCoord = {Ve} 
RSQ fogCoord.x, fogCoord.x; 
RCP oFgC.x, fogCoord.x; 


END 


The calculation to find the distance from the eye (0,0,0,1) to the vertex in eye space is 
trivial in GLSL. You need only call the built-in length function, passing in the vertex posi- 
tion vector as an argument. In the low-level shader, you must manually perform the same 
operation. First, you take the dot product of the vertex position against itself followed by 
the reciprocal square root, just as if you were normalizing the vector. But instead of multi- 
plying this 1/length scale factor by the vector, you just take its reciprocal so the 1/length 
becomes the length, which is output directly as the vertex’s fog coordinate. 


The following is the altered GLSL code for performing the fog blend within the shader 
instead of in fixed functionality fragment processing: 


uniform float density; 


// calculate 2nd order exponential fog factor 
const float e = 2.71828; 

float fogFactor = (density * length(V)); 
fogFactor *= fogFactor; 

fogFactor = clamp(pow(e, -fogFactor), 0.0, 1.0); 


// sum the diffuse and specular components, then 

// blend with the fog color based on fog factor 

const vec4 fogColor = vec4(0.5, 0.8, 0.5, 1.0); 

gl_FrontColor = mix(fogColor, clamp(diffuse + specular, 0.0, 1.0), 
fogFactor) ; 


The altered low-level shader code is as follows: 


PARAM density = program.local[1]; # fog density 
PARAM fogColor = {0.5, 0.8, 0.5, 1.0}; # fog color 
PARAM e = {2.71828, 0, 0, 0}; 


TEMP diffuse, specular, fogFactor, litColor; 


Per-Vertex Point Size 


ADD litColor, diffuse, specular; # sum the colors 
MAX 1itColor, litColor, 0.9; # clamp to [0,1] 
MIN litColor, litColor, 1.0; 


# fogFactor = clamp(e*(-(d*{|Ve;)*2)) 

DP4 fogFactor.x, V, V; 

POW fogFactor.x, fogFactor.x, 0.5.x; 

MUL fogFactor.x, fogFactor.x, density.x; 

MUL fogFactor.x, fogFactor.x, fogFactor.x; 

POW fogFactor.x, e.x, -fogFactor.x; 

MAX fogFactor.x, fogFactor.x, 0.0; # clamp to [0,1] 
MIN fogFactor.x, fogFactor.x, 1.0; 


SUB litColor, litColor, fogColor; # blend lit and fog colors 
MAD oPrC, fogFactor.x, litColor, fogColor; 


END 


Per-Vertex Point Size 


Applying fog attenuates object colors the farther away they are from the viewpoint. 
Similarly, you can attenuate point sizes so that points rendered close to the viewpoint are 
relatively large and points farther away diminish into nothing. Like fog, point attenuation 
is a useful visual cue for conveying perspective. The computation required is similar as 
well. 


You compute the distance from the vertex to the eye exactly the same as you did for the 
fog coordinate. Then, to get a point size that falls off exponentially with distance, you 
square the distance, take its reciprocal, and multiply it by the constant 100,000. This 
constant is chosen specifically for this scene’s geometry so that objects toward the back of 
the scene, as rendered from the initial camera position, are assigned point sizes of approxi- 
mately 1, whereas points near the front are assigned point sizes of approximately 10. 


In this sample application, you'll set the polygon mode for front- and back-facing poly- 
gons to GL_POINT so that all the objects in the scene are drawn with points. Also, you must 
enable GL_VERTEX_PROGRAM_POINT_SIZE_ARB so that the point sizes output from the vertex 
shader are substituted in place of the usual OpenGL point size. Figure 22.7 shows the 
result of Listings 22.11 and 22.12. 
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3 Vertex Shaders Demo 


FIGURE 22.7 Per-vertex point size makes distant points smaller. 


LISTING 22.11 Point Size Generating High-Level Vertex Shader 


// ptsize.vs 


// 


// Generic vertex transformation, 
// attenuated point size 


void main(void) 


{ 


// normal MVP transform 
gl_Position = gl_ModelViewProjectionMatrix * gl Vertex; 


vec4 V = gl ModelViewMatrix * gl Vertex; 
gl_FrontColor = gl Color; 

// calculate point size based on distance from eye 
float ptSize = length(V); 


ptSize *= ptSize; 
gl_PointSize = 100000.0 / ptSize; 


Per-Vertex Point Size 


LISTING 22.12 Point Size Generating Low-Level Vertex Shader 


! !ARBvp1. 


# ptsize.vs 

# 

# Generic vertex transformation, 
# attenuated point size 


ATTRIB iPos = vertex.position; 
ATTRIB iPrC = vertex.color.primary; 


OUTPUT oPos = result.position; 
OUTPUT oPrC = result.color.primary; 
OUTPUT oPtS = result.pointsize; 


PARAM mvp[4] = { state.matrix.mvp }; 
PARAM mv[4] = { state.matrix.modelview 


TEMP V, ptSize; 


DP4 oPos.x, iPos, mvp[0]; 
DP4 oPos.y, iPos, mvp[1]; 
DP4 oPos.z, iPos, mvp[2]; 
DP4 oPos.w, iPos, mvp[3]; 


DP4 V.x, iPos, mv[Q]; 
DP4 V.y, iPos, mv[1]; 
DP4 V.z, iPos, mv[2]; 
DP4 V.w, iPos, mv[3]; 


MOV oPrC, iPrc; 


DP4 ptSize.x, V, V; 

RSQ ptSize.x, ptSize.x; 

MUL ptSize.x, ptSize.x, ptSize.x; 
MUL oPtS.x, ptSize.x, 100000; 


input position 
input primary color 


output position 
output primary color 


output point size 


modelview * proj matrix 
modelview matrix 


temporary registers 


xform input pos by MVP 


xform input pos by MV 


copy color 


ptSize = 100000 / |Ve;*2 
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Customized Vertex Transformation 


You've already customized lighting, texture coordinate generation, and fog coordinate 
generation. But what about the vertex positions themselves? The next sample shader 
applies an additional transformation before transforming by the usual modelview/projec- 
tion matrix. 


Figure 22.8 shows the effects of scaling the object-space vertex position by a squash 
and stretch factor, which can be set independently for each axis, as in Listings 22.13 and 
22.14. 


Vertex Shaders Demo 


FIGURE 22.8 Squash and stretch effects customize the vertex transformation. 


LISTING 22.13 Squash and Stretch High-Level Vertex Shader 


// stretch.vs 

// 

// Generic vertex transformation, 
// followed by squash/stretch 


uniform vec3 lightPosQ; 
uniform vec3 squashStretch; 


void main(void) 


{ 


Customized Vertex Transformation 


LISTING 22.13 Continued 


// normal MVP transform, followed by squash/stretch 

vec4 stretchedCoord = gl Vertex; 

stretchedCoord.xyz *= squashStretch; 

gl_Position = gl_ModelViewProjectionMatrix * stretchedCoord; 


vec3 stretchedNormal = gl_Normal; 
stretchedNormal *= squashStretch; 
vec3 N = normalize(gl_NormalMatrix * stretchedNormal) ; 


vec4 V = gl ModelViewMatrix * stretchedCoord; 
vec3 L = normalize(lightPos® - V.xyz); 
vec3 H = normalize(L + vec3(0.0, 0.0, 1.0)); 


// put diffuse lighting result in primary color 
float NdotL = dot(N, L); 
gl_FrontColor = gl Color * vec4(max(®.0, NdotL)); 


// copy (N.H)*8-7 into texcoord 
float NdotH = max(@.@, dot(N, H) * 8.@ - 7.0); 
gl_TexCoord[0] = vec4(NdotH, 0.0, 0.0, 1.0); 


LISTING 22.14 Squash and Stretch Low-Level Vertex Shader 
! !ARBvp1.0 


# stretch.vs 

# 

# Generic vertex transformation, 
# followed by squash/stretch 


ATTRIB iPos = vertex.position; # input position 

ATTRIB iPrC = vertex.color.primary; # input primary color 
ATTRIB iNrm = vertex.normal; # input normal 

OUTPUT oPos = result.position; # output position 

OUTPUT oPrC = result.color.primary; # output primary color 
OUTPUT oTxC = result.texcoord[Q]; # output texcoord 0 

PARAM mvp[4] = { state.matrix.mvp }; # modelview * proj matrix 


PARAM mv[4] = { state.matrix.modelview }; # modelview matrix 
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LISTING 22.14 Continued 


# inverse transpose of modelview matrix: 
PARAM mvIT[4] = { state.matrix.modelview.invtrans }; 


PARAM lightPos = program.local[0]; # light pos in eye space 
PARAM squashStretch = program.local[1]; # stretch scale factors 


TEMP N, V, L, H, NdotL, NdotH, ssV, ssN; # temporary registers 


MUL 
MUL 


pP4 
pP4 
DP4 
pP4 


DP4 
DP4 
DP4 
DP4 


SUB 


DP3 
DP3 
DP3 


DP3 
RSQ 
MUL 


DP3 
RSQ 
MUL 


ADD 


DP3 


RSQ 
MUL 


ssV, iPos, squashStretch; 
ssN, iNrm, squashStretch; 


oPos.x, ssV, mvp[Q]; 
oPos.y, ssV, mvp[1]; 
oPos.z, ssV, mvp[2]; 
oPos.w, ssV, mvp[3]; 


V.xX, SSV, mv[0]; 
V.y, ssV, mv[1]; 
V.z, ssV, mv[2]; 
V.w, ssV, mv[3]; 


L, lightPos, V; 


N.xX, SSN, mvIT[Q]; 
N.y, SSN, mvIT[1]; 
N.z, SSN, mvIT[2]; 


N.w, N, Nj 
N.w, N.w; 
N, N, N.w; 


Low, Lb, ‘Ls 
L.w, L.w; 
Le. bs Ley 


H.xyz,. Ly {0, @, 1}s 
H.w, H, H; 


H.w, H.w; 
H, H, H.w; 


stretch obj-space vertex 
stretch obj-space normal 


xform stretch pos by MVP 


xform stretch pos by MV 


vertex to light vector 


xform stretched normal 


normalize normal 


normalize light vector 


normalize half-angle 


LISTING 22.14 Continued 


DP3 
MAX 
MUL 


DP3 
MAD 
MOV 
MAX 


END 


NdotL, N, L; 
NdotL, NdotL, 0.0; 
oPrC, iPrC, NdotL; 


NdotH, N, H; 

NdotH.x, NdotH, 8.0, {-7.0}; 
OTxC, {0.0, 0.0, 0.0, 1.0}; 
oTxC.x, NdotH, 0.0; 


Vertex Blending 


#N.L 


# output diffuse 


# toss into texcoord 0 


Vertex Blending 


Vertex blending is an interesting technique used for skeletal animation. Consider a simple 
model of an arm with an elbow joint. The forearm and bicep are each represented by a 
cylinder. When the arm is completely straight, all the “skin” is nicely connected together. 
But as soon as you bend the arm, as in Figure 22.9, the skin is disconnected and the 
realism is gone. 
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Vertex Blending D 


FIGURE 22.9 This simple elbow joint without vertex blending just begs for skin. 
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The way to fix this problem is to employ multiple modelview matrices when transforming 
each vertex. Both the forearm and bicep have their own modelview matrix already. The 
bicep’s matrix would orient it relative to the torso if it were attached to a body, or in this 
case relative to the origin in object-space. The forearm’s matrix orients it relative to the 
bicep. The key to vertex blending is to use a little of each matrix when transforming 
vertices close to a joint. 


You can choose how close to the joint you want the multiple modelview matrices to have 
influence. We call this the region of influence. Vertices outside the region of influence do 
not require blending. For such a vertex, only the original modelview matrix associated 
with the object is used. However, vertices that do fall within the region of influence must 
transform the vertex twice: once with its own modelview matrix and once with the matrix 
belonging to the object on the other side of the joint. For this sample, you blend these 
two eye-space positions together to achieve the final eye-space position. 


The amount of one eye-space position going into the mix versus the other is based on the 
vertex’s blend weight. When drawing the glBegin/glEnd primitives, in addition to the 
usual normals, colors, and positions, you also specify a weight for each vertex. You use the 
glVertexAttrib1fARB function for specifying the weight. Vertices right at the edge of the 
joint receive weights of 0.5, effectively resulting in a 50% influence by each matrix. On 
the other extreme, vertices on the edge of the region of influence receive weights of 1.0, 
whereby the object’s own matrix has 100% influence. Within the region of influence, 
weights vary from 1.0 to 0.5, and they can be assigned linearly with respect to the 
distance from the joint, or based on some higher-order function. 


Any other computations dependent on the modelview matrix must also be blended. In the 
case of the sample shader, you also perform diffuse and specular lighting. This means the 
normal vector, which usually is transformed by the inverse transpose of the modelview 
matrix, now must also be transformed twice just like the vertex position. The two results 
are blended based on the same weights used for vertex position blending. 


By using vertex blending, you can create life-like flexible skin on a skeleton structure that 
is easy to animate. Figure 22.10 shows the arm in its new Elastic Man form, thanks to a 
region of influence covering the entire arm. Listings 22.15 and 22.16 contain the vertex 
blending shader source. 


[Vertex Blending Demo 


“=, 


FIGURE 22.10 The stiff two-cylinder arm is now a fun, curvy, flexible object. 


LISTING 22.15 Vertex Blending High-Level Vertex Shader 


// skinning.vs 

// 

// Perform vertex skinning by 
// blending between two MV 

// matrices 


uniform vec3 lightPos; 
uniform mat4 mv2; 
uniform mat3 mv2IT; 
attribute float weight; 


void main(void) 
{ 
// compute each vertex influence 
vec4 V1 = gl ModelViewMatrix * gl Vertex; 


Vertex Blending 
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LISTING 22.15 Continued 


vec4 V2 = mv2 * gl Vertex; 
vec4 V = (V1 * weight) + (V2 * (1.@ - weight)); 
gl_Position = gl ProjectionMatrix * V; 


// compute each normal influence 
vec3 N1 = gl_NormalMatrix * gl Normal; 
vec3 N2 = mv2IT * gl Normal; 


vec3 N = normalize((N1 * weight) + (N2 * (1.0 - weight))); 
vec3 L = normalize(lightPos - V.xyz); 
vec3 H = normalize(L + vec3(@.0, 0.0, 1.0)); 


// put diffuse lighting result in primary color 
float NdotL = dot(N, L); 
gl_FrontColor = @.1 + gl Color * vec4(max(®@.0, NdotL)); 


// copy (N.H)*8-7 into texcoord 
float NdotH = max(@.@, dot(N, H) * 8.@ - 7.0); 
gl_TexCoord[®] = vec4(NdotH, 0.0, 0.0, 1.0); 


LISTING 22.16 Vertex Blending Low-Level Vertex Shader 
! LARBvp1.@ 


# skinning.vp 

# 

# Perform vertex skinning by 
# blending between two MV 

# matrices 


ATTRIB iPos = vertex.position; # input position 
ATTRIB iPrC = vertex.color.primary; # input primary color 
ATTRIB iNrm = vertex.normal; # input normal 

ATTRIB iWeight = vertex.attrib[1]; # input weight 

OUTPUT oPos = result.position; # output position 
OUTPUT oPrC = result.color.primary; # output primary color 
QUTPUT oTxC = result.texcoord[0]; # output texcoord 0 


PARAM prj(4] = { state.matrix.projection }; # projection matrix 


LISTING 22.16 Continued 


PARAM mvi[4] = { state.matrix.modelview }; 


ca 


Vertex Blending 


modelview matrix 1 


PARAM mv2[4] = { state.matrix.program[®] }; # modelview matrix 2 


# inverse transpose of modelview matrix: 


PARAM mv1IT[4] 
PARAM mv2IT[4] 


PARAM lightPos 


= { state.matrix.modelview.invtrans }; 


i} 


= program.local[0]; 


TEMP N1, N2, N, V1, V2, V; 
TEMP L, H, NdotL, NdotH; 


DP4 
DP4 
DP4 
pP4 


DP4 
DP4 
DP4 
DP4 


SUB 
MAD 


DP4 
DP4 
DP4 
DP4 


SUB 


DP3 
DP3 
DP3 


DP3 
DP3 
DP3 


SUB 
MAD 


v1 
v1 
v1 
v1 


v2. 
v2. 
«Z, iPos, 
-w, iPos, 


aX, A POS; 
sy, iPos, 
~Z,. 2P0S, 
.wW, iPos, 


x, iPos, 
y, iPos, 


V1, V2; 


mv1[@]; 
mvi[1]; 
mvi[2]; 
mv1[3]; 


mv2[@]; 
mv2[1]; 
mv2[2]; 
mv2[3]; 


V, V, iWeight.x, V2; 


oPos.x, 


oPos.z, 
oPos.w, 


V, 
oPos.y, V, 
Vv, 
V, 


prj[0]; 
prjtt]; 
prj(2]; 
prj[3]; 


L, lightPos, V; 


N1 
N1 
N1 


-x, iNrm, 
-y, iNrm, 
-z, iNrm, 


.x, iNrm, 
-y, iNrm, 
.z, iNrm, 


N1, N2; 


mv1IT[O]; 
mv1IT[1]; 
mv1IT[2]; 


mv2IT[0]; 
mv2IT[1]; 
mv2IT[2]; 


N, iWeight.x, N2; 


# 


= { state.matrix.program[®].invtrans }; 


light pos in eye space 


temporary registers 


xform input pos by MV1 


xform input pos by MV2 


blend verts w/ weight 


xform to clip space 


vertex to light vector 


xform norm to eye space 


xform norm to eye space 


blend normals w/ weight 
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LISTING 22.16 Continued 


DP3 N.w, N, N; # normalize normal 
RSQ N.w, N.w; 
MUL N, N, N.w; 


DP3 L.w, L, L; # normalize light vector 
RSQ L.w, L.w; 
MUL L, L, L.w; 


ADD H.xyz, L, {0, ®, 1}; 


DP3 H.w, H, H; # normalize half -angle 
RSQ H.w, H.w; 

MUL H, H, H.w; 

DP3 NdotL, N, L; #N.L 


MAX NdotL, NdotL, 0.0; 


MAD oPrC, iPrC, NdotL, 0.1; # output diffuse 

DP3 NdotH, N, H; #N-H 

MAD NdotH.x, NdotH, 8.0, {-7.0}; #(N-H)* 8-7 

MOV oTXC, {0.0, 0.0, 0.0, 1.0}; 

MAX oTxC.x, NdotH, 0.0; # toss into texcoord 0 
END 


In this sample, you use built-in modelview matrix uniforms (GLSL) or parameters (low- 
level) to access the primary blend matrix. For the secondary matrix, you employ a user- 
defined uniform matrix (GLSL) or program matrix (low-level). 


For normal transformation, you need the inverse transpose of each blend matrix. 
Although low-level shaders provide a simple way to access the inverse transpose of a 
matrix, high-level shaders do not. You continue to use the built-in gl_NormalMatrix for 
accessing the primary matrix’s inverse transpose, but for the secondary matrix’s inverse 
transpose, there is no shortcut. Instead, you manually compute the inverse of the second 
modelview matrix within the application and transpose it on the way into OpenGL when 
calling g1UniformMatrix3fvARB. 


Summary 


Summary 


This chapter provided various sample shaders as a jumping-off point for your own explo- 
ration of high- and low-level vertex shaders. Specifically, we provided examples of 
customized lighting, texture coordinate generation, fog, point size, and vertex transforma- 
tion. 


It is refreshing to give vertex shaders their moment in the spotlight. In reality, vertex 
shaders often play only supporting roles to their fragment shader counterparts, performing 
menial tasks such as preparing texture coordinates. Fragment shaders end up stealing the 
show. In the next chapter, we’ll start by focusing solely on fragment shaders. Then in the 
stunning conclusion, we will see our vertex shader friends once again when we combine 
the two shaders and say goodbye to fixed functionality once and for all. 
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CHAPTER 23 


Fragment Shading: Empower Your 
Pixel Processing 


by Benjamin Lipchak 


WHAT YOU'LL LEARN IN THIS CHAPTER: 


¢ How to alter colors 

¢ How to post-process images 

¢ How to light an object per-fragment 

¢ How to perform procedural texture mapping 


As you may recall from Chapter 19, “Programmable Pipeline: This Isn’t Your Father’s 
OpenGL,” fragment shaders replace the texturing, color sum, and fog stages of the fixed 
functionality pipeline. This is the section of the pipeline where the party is happening. 
Instead of marching along like a mindless herd of cattle, applying each enabled texture 
based on its pre-ordained texture coordinate, your fragments are free to choose their own 
adventure. Mix and match textures and texture coordinates. Or calculate your own texture 
coordinates. Or don’t do any texturing, and just compute your own colors. It’s all good. 


In their natural habitat, vertex shaders and fragment shaders are most often mated for life. 
Fragment shaders are the dominant partner, directly producing the eye candy you see 
displayed on the screen, and thus they receive the most attention. However, vertex 
shaders play an important supporting role. In the name of performance, as much of the 
grunt work as possible is pushed into vertex shaders because they tend to be executed 
much less frequently (except for the smallest of triangles). The results are then placed into 
interpolants for use as input by the fragment shader. The vertex shader is a selfless 
producer; the fragment shader a greedy consumer. 


In this chapter, we continue the learning by example we began in the preceding chapter. 
We present many fragment shaders, both as further exposure to the low-level and high- 
level shading languages, and as a launch pad for your own future dabbling. Because you 
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rarely see fragment shaders alone, once you get the hang of fragment shaders in isolation, 
we will move on to discuss several examples of vertex shaders and fragment shaders 
working together in peaceful harmony. 


Color Conversion 


We almost have to contrive some examples illustrating where fragment shaders are used 
without vertex shader assistance. But we can easily separate them where we simply want 
to alter the existing color. For these examples, we use fixed functionality lighting to 
provide a starting color. Then we go to town on it. 


Grayscale 

One thing you might want to do in your own work is simulate black-and-white film. 
Given the incoming red, green, and blue color channel intensities, we would like to calcu- 
late a single grayscale intensity to output to all three channels. Red, green, and blue each 
reflect light differently, which we represent by their different contributions to the final 
intensity. 


Listings 23.1 and 23.2 show the GLSL and ARB_fragment_program versions of the shader. 
Though you won't be able to distinguish between several of the shader results due to the 
black-and-white limitations of the figures, Figure 23.1 is provided as a reference for some 
of the other shader results that are distinguishable. 


3 Fragment Shaders Demo 


FIGURE 23.1 This fragment shader converts the RGB color into a single grayscale value. 


Color Conversion 


LISTING 23.1 Grayscale Conversion High-Level Fragment Shader 


// grayscale.fs 
// 
// convert RGB to grayscale 


void main(void) 


{ 
// Convert to grayscale 
float gray = dot(gl_Color.rgb, vec3(@.3, @.59, @.11)); 
// replicate grayscale to RGB components 
gl_FragColor = vec4(gray, gray, gray, 1.0); 
} 


LISTING 23.2 Grayscale Conversion Low-Level Fragment Shader 
!!ARBfp1.@ 


# grayscale.fp 
# 
# convert RGB to grayscale 


ATTRIB iPrC = fragment.color.primary; # input primary color 


OUTPUT oPrC = result.color; # output color 


DP3 oPrC.rgb, iPrC, {0.3, ®.59, @.11};# R,G,B each contribute diff. 
MOV oPrC.a, 1.0; # init alpha to 1 


END 


The key to all these fragment shaders is that what you write to the color output 
(gl_FragColor or result.color) is what is passed along down the rest of the OpenGL 
pipeline, eventually to the framebuffer. The primary color inputs are gl_Color and 
fragment.color.primary, respectively. 


Try playing with the contributions of each color channel. Notice how they add up to 1. 
You can simulate overexposure by making them add up to more than 1, while less than 1 
will simulate underexposure. 


Sepia Tone 


In this next example, we recolorize the grayscale picture with a sepia tone. This tone gives 
the picture the tint of an old Western photograph. To do this, we first convert to grayscale 
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as before. Then we multiply the gray value by a color vector, which accentuates some 
color channels and reduces others. Listings 23.3 and 23.4 illustrate this sepia-tone conver- 
sion. 


LISTING 23.3 Sepia-Tone Conversion High-Level Fragment Shader 


// sepia.fs 
// 
// convert RGB to sepia tone 


void main(void) 


{ 
// Convert RGB to grayscale 
float gray = dot(gl_Color.rgb, vec3(0.3, 0.59, @.11)); 
// convert grayscale to sepia 
gl_FragColor = vec4(gray * vec3(1.2, 1.0, 0.8), 1.0); 
} 


LISTING 23.4 Sepia-Tone Conversion Low-Level Fragment Shader 
!!ARBfp1.0 


# sepia.fp 
# 
# convert RGB to sepia tone 


ATTRIB iPrC = fragment.color.primary; # input primary color 


OUTPUT oPrC = result.color; # output color 
TEMP gray; 
DP3 gray, iPrC, {0.3, 0.59, 0.11}; # convert to grayscale 


MUL oPrC.rgb, gray, {1.2, 1.0, @.8}; # convert to sepia 
MOV oPrC.a, 1.0; # init alpha to 1 


END 


You can choose to colorize with any tint you like. Go ahead and play with the tint factors. 
Here, we've hard-coded one for sepia. If you’re truly ambitious, you could substitute 
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external application-defined constants (uniforms in GLSL, program parameters in 
ARB_fragment_program) to make the tint color user-selectable so you don’t have to write a 
different shader for every tint color. 


Inversion 


For this next example, we’re going for the film negative effect. These shaders are almost 
too simple to mention. All you have to do is take whatever color you were otherwise 
going to draw and subtract that color from 1. Black becomes white, and white becomes 
black. Red becomes cyan. Purple becomes chartreuse. You get the picture. 


€Z 


Figure 23.2 illustrates the color inversion performed in Listings 23.5 and 23.6. Use your 
imagination or consult the sample code for the grayscale inversion, which is just as 
straightforward. 


3 Fragment Shaders Demo 


i 


~ 


Bees 


FIGURE 23.2 This fragment shader inverts the RGB color, yielding a film negative effect. 


// colorinvert.fs 
/I 
// invert like a color negative 


void main(void) 


4 
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LISTING 23.5 Continued 


// invert color components 
gl_FragColor.rgb = 1.0 - gl_Color.rgb; 
gl_FragColor.a = 1.0; 


LISTING 23.6 Color Inversion Low-Level Fragment Shader 
!!ARBfp1.@ 


# colorinvert.fp 
# 
# invert like a color negative 


ATTRIB iPrC = fragment.color.primary; # input primary color 


OUTPUT oPrC = result.color; # output color 

SUB oPrC.rgb, 1.0, iPrc; # invert RGB colors 
MOV oPrC.a, 1.0; # init alpha to 1 
END 


Heat Signature 


Now, we attempt our first texture lookup. In this sample shader, we simulate a heat signa- 
ture effect like the one in the movie Predator. Heat is represented by a color spectrum 
ranging from black to blue to green to yellow to red. 


We again use the grayscale conversion, this time as our scalar heat value. We use this value 
as a texture coordinate to index into a 1D texture populated with the color gradients from 
black to red. Figure 23.3 shows the results of the heat signature shaders in Listings 23.7 
and 23.8. 


LISTING 23.7 Heat Signature High-Level Fragment Shader 


// heatsig.fs 
// 
// map grayscale to heat signature 


uniform sampleriD samplerQ; 


Color Conversion 


LISTING 23.5 Continued 


void main(void) 


{ 
// Convert to grayscale 
float gray = dot(gl_Color.rgb, vec3(@.3, @.59, @.11)); 
// lookup heatsig value 
gl_FragColor = texture1D(sampler®, gray); 
} 


3 Fragment Shaders Demo 


FIGURE 23.3 This fragment shader simulates a heat signature by looking up a color from a 
1D texture. 


LISTING 23.8 Heat Signature Low-Level Fragment Shader 
| LARBfp1.0 

# heatsig.fp 

# 


# map grayscale to heat signature 


ATTRIB iPrC = fragment.color.primary; # input primary color 
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LISTING 23.6 Continued : 
OUTPUT oPrC = result.color; # output color 


TEMP gray; 
DP3 gray, iPrC, {0.3, 0.59, 0.11}; #R,G,B -> gray 
TEX oPrC, gray, texture[@], 1D; # lookup heatsig value 


END 


In the low-level shader, notice how we reference the texture unit from which we want to 
look up as texture[0]. The texture unit is effectively hard-coded into the shader. This is in 
contrast to the GLSL shader, which uses a special sampler uniform that can be set within 
the application. 


Dependent Texture Lookups 

Fixed functionality texture mapping was very strict, requiring all texture lookups to use an 
interpolated per-vertex texture coordinate. One of the powerful new capabilities made 
possible by fragment shaders is that you can calculate your own texture coordinates per- 
fragment. You can even use the result of one texture lookup as the coordinate for another 
lookup. All these cases are considered dependent texture lookups. They’re named that 
because the lookups are dependent on other preceding operations in the fragment shader. 


You may not have noticed, but we just performed a dependent texture lookup in the heat 
signature shader. First, we had to compute our texture coordinate by doing the grayscale 
conversion. Then we used that value as a texture coordinate to perform a dependent 
texture lookup into the 1D heat signature texture. 


The dependency chain can continue: You could, for example, take the color from the heat 
texture and use that as a texture coordinate to perform a lookup from a cube map texture, 
perhaps to gamma-correct your color. Beware, however, that some OpenGL implementa- 
tions have a hardware limit as to the length of dependency chains, so keep this point in 
mind if you want to avoid falling into a non—hardware-accelerated driver path! 


Per-Fragment Fog 

Instead of performing fog blending per-vertex, or calculating the fog factor per-vertex and 
using fixed functionality fog blending, we compute the fog factor and perform the blend 
ourselves within the fragment shader in the following example. This example emulates 
GL_EXP2 fog mode except that it will be more accurate than most fixed functionality 
implementations, which apply the exponentiation per-vertex instead of per-fragment. This 
is most noticeable on low-tesselation geometry that extends from the foreground to the 
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background, such as the floor upon which all the objects in the scene rest. Compare the 
results of this shader with the fog shaders in the preceding chapter, and you can readily 
see the difference. 


Figure 23.4 illustrates the output of the fog shader in Listings 23.9 and 23.10. 


[3 Fragment Shaders Demo 


FIGURE 23.4 This fragment shader performs per-fragment fog computation. 


LISTING 23.9 Per-Fragment Fog High-Level Fragment Shader 


// fog.fs 
// 
// per-pixel fog 


uniform float density; 


void main(void) 


{ 
const vec4 fogColor = vec4(0.5, 0.8, 0.5, 1.0); 


// calculate 2nd order exponential fog factor 
// based on fragment's Z distance 
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LISTING 23.9 Continued 


const float e = 2.71828; 

float fogFactor = (density * gl_FragCoord.z); 
fogFactor *= fogFactor; 

fogFactor = clamp(pow(e, -fogFactor), 0.0, 1.0); 


// Blend fog color with incoming color 
gl_FragColor = mix(fogColor, gl_Color, fogFactor) ; 


LISTING 23.10 Per-Fragment Fog Low-Level Fragment Shader 


!LARBfp1.0 


# fog.fp 


# 


# per-pixel fog 


ATTRIB iPr 


fragment.color.primary; # input primary color 


ATTRIB iFrP = fragment.position; # input fragment position 
OUTPUT oPrC = result.color; # output color 
PARAM density = program.local[0]; # fog density 


PARAM fogColor = {@.5, 0.8, 0.5, 1.0}; # fog color 
PARAM e = {2.71828, 0, 0, 0}; 


TEMP fogFactor; 


# fogFactor = clamp(e*(-(d*Zw) *2) ) 

MUL fogFactor.x, iFrP.z, density.x; 

MUL fogFactor.x, fogFactor.x, fogFactor.x; 

POW fogFactor.x, e.x, -fogFactor.x; 

MAX fogFactor.x, fogFactor.x, 0.0; # clamp to [0,1] 
MIN fogFactor.x, fogFactor.x, 1.0; 


LRP oPrC, fogFactor.x, iPrC, fogColor; # blend lit and fog colors 


END 


Image Processing 


We need to comment on a few things here. One is the instructions used to blend. On the 
one hand, we have GLSL’s built-in mix function. On the other hand, we have the LRP 
instruction in the low-level shader, which is specific to ARB_fragment_program. LRP is not 
available in ARB_vertex_program, where you have to perform blending with a combina- 
tion of instructions, such as SUB and MAD. 


Another thing to notice is how we have chosen to make the density an externally set 
constant rather than a hard-coded one. This way, we can tie the density to keystrokes. 
When the user hits the left or right arrows, we update the density shader constant with a 
new value without having to change the shader text at all. As a general rule, constant 
values that you may want to change at some point should not be hard-coded, but all 
others should be. By hard-coding a value, you give the OpenGL implementation’s optimiz- 
ing compiler an early opportunity to use this information to possibly make your shader 
run even faster. 


Now that we’ve already created fog the hard way, we can use a low-level 
ARB_fragment_program extension shortcut that actually lets us request fog with a single 
line: 


1 LARBFp1.0 
OPTION ARB_fog exp2; 


Also available are ARB_fog_exp and ARB_fog_linear. These shortcuts were made available 
to ease the transition for application developers who were accustomed to the convenience 
of just setting glEnable(GL_FOG). 


Image Processing 


Image processing is another application of fragment shaders that doesn’t depend on vertex 
shader assistance. After drawing the scene without fragment shaders, we can apply convo- 
lution kernels to post-process the image in a variety of ways. 


To keep the shaders concise and improve the probability of their being hardware- 
accelerated on a wider range of hardware, we’ve limited the kernel size to 3x3. Feel free 
to experiment with larger kernel sizes. 


Within the sample application, g1CopyTexImage2D is called to copy the contents of the 
framebuffer into a texture. The texture size is chosen to be the largest power-of-2 size 
smaller than the window. A fragment-shaded quad is then drawn centered within the 
window with the same dimensions as the texture, with a base texture coordinate ranging 
from (0,0) in the lower left to (1,1) in the upper right. 


The fragment shader takes its base texture coordinate and performs a texture lookup to 
obtain the center sample of the 3x3 kernel neighborhood. It then proceeds to apply eight 
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different offsets to lookup samples for the other eight spots in the neighborhood. Finally, 
the shader applies some filter to the neighborhood to yield a new color for the center of 
the neighborhood. Each sample shader provides a different filter commonly used for 
image-processing tasks. 


Blur 


Blurring may be the most commonly applied filter in everyday use. It smoothes out high- 
frequency features, such as the jaggies along object edges. It is also called a low-pass filter 
because it lets low-frequency features pass through while filtering out high-frequency 
features. 


Because we’re using only a 3x3 kernel, the blur is not overly dramatic in a single pass. We 
could make it more blurry by using a larger kernel or, as we do here, by applying the blur 
filter multiple times in successive passes. Figure 23.5 shows the results of the blur filter in 
Listings 23.11 and 23.12 after five passes. 


3 image Processing Demo 


FIGURE 23.5 This fragment shader blurs the scene. 


LISTING 23.11 Post-Process Blur High-Level Fragment Shader 


// blur.fs 
// 
// blur (low-pass) 3x3 kernel 


LISTING 23.11 


uniform sampler2D samplerQ; 
uniform vec2 tc_offset[9]; 


Continued 


void main(void) 


{ 
vec4 sample[9]; 
for (int i = 0; i < 9; i++) 
{ 
sample[i] = texture2D(sampler®Q, 
gl_TexCoord[@].st 
} 
ih “te2eA 
ii e222  A8 
Him WV2Al 
gl_FragColor = (sample[0] + (2.0*sample[1]) 
(2.0*sample[3]) + sample[4] 
sample[6] + (2.0*sample[7]) 
} 


Image Processing 


+ 


+ 
+ 
+ 


tc_offset[i]); 


sample[2] + 
(2.@*sample[5]) + 
sample[8]) / 13.0; 


LISTING 23.12 Post-Process Blur Low-Level Fragment Shader 


!!ARBfp1.0 


# blur.fp 
# 
# blur (low-pass) 3x3 kernel 


ATTRIB iTCO = fragment.texcoord[®]; 


OUTPUT oPrC = result.color; 


TEMP tc®, tcl, tc2, tc3, te4, tc5, tce6, tce7, tc8; 


ADD tc, 
ADD tc1, 
ADD tc2, 
ADD tc3, 
ADD tc4, 


iTC®, program.local[Q]; 
iTC®, program.local[1]; 
iTC®, program.local[2]; 
iTC®, program.local[3]; 
iTC®, program.local[4]; 


# input texcoord 


# output color 
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LISTING 23.12 Continued 


ADD tc5, iTC®, program.local[5]; 
ADD tc6, iTC®, program.local[6]; 
ADD tc7, iTC@, program.local[7]; 
ADD tc8, iTC®, program.local[8]; 
TEX tc0, tc®, texture[@], 2D; 
TEX tc1, tc1, texture[@], 2D; 
TEX tc2, tc2, texture[@], 2D; 
TEX tc3, tc3, texture[®], 2D; 
TEX tc4, tc4, texture[@], 2D; 
TEX tc5, tc5, texture[Q@], 2D; 
TEX tc6, tc6, texture[@], 2D; 
TEX tc7, tc7, texture[@], 2D; 
TEX tc8, tc8, texture[@], 2D; 


{ 
2 / 18 

{ 

ADD tc@, tc®, tc2; 

ADD tc2, tc4, tc6; 

ADD tc®, tc®, tc2; 

ADD tc®, tc®, tc8; 

ADD tc1, tc1, tc3; 

ADD tc3, tc5, tc7; 

ADD tc1, tc1, tc3; 

MAD tc, tc1, 2.0, tcQ; 


MUL oPrC, tc0, 0.076923; # 1/13 


END 


The first thing we do in the blur shaders is generate our nine texture coordinates. This is 
accomplished by adding precomputed constant offsets to the interpolated base texture 
coordinate. The offsets were computed taking into account the size of the texture such 
that the neighboring texels to the north, south, east, west, northeast, southeast, north- 
west, and southwest could be obtained by a simple 2D texture lookup. In the low-level 
version, texture[®] indicates that the texture lookup takes place on texture unit 0. In the 
GLSL version, you have to use a special-purpose uniform called a sampler, just as we did in 
the heat sampler. The sampler is loaded outside the shader to reflect which texture unit is 
in play. 


Image Processing 


This neighborhood is obtained the same way in all our image processing shaders. It is the 
filter applied to the neighborhood that differs in each shader. In the case of the blur filter, 
the texel neighborhood is multiplied by a 3x3 kernel of coefficients (1s and 2s), which add 
up to 13. The resulting values are all summed and averaged by dividing by 13, resulting in 
the new color for the texel. Note that we could have made the kernel coefficient values 
1/13 and 2/13 instead of 1 and 2, but that would have required many extra multiplies. It 
is simpler and cheaper for us to factor out the 1/13 and just apply it at the end. 


Try experimenting with the filter coefficients. What if, for example, you put a weight of 1 
at each corner and then divide by 4? Notice what happens when you divide by more or 
less than the sum of the coefficients: The scene grows darker or lighter. That makes sense. 
If your scene were all white, you would be effectively multiplying the filter coefficients by 
1 and adding them up. If you don’t divide by the sum of the coefficients, you’ll end up 
with a color other than white. 


Sharpen 


Sharpening is the opposite of blurring. Some examples of its use include making edges 
more pronounced and making text more readable. Figure 23.6 illustrates the use of sharp- 
ening, applying the filter in two passes. 


[3 Image Processing Demo 


FIGURE 23.6 This fragment shader sharpens the scene. 
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Here is the GLSL code for applying the sharpen filter: 


// sharpen.fs 
// 
// 3x3 sharpen kernel 


uniform sampler2D samplerd; 
uniform vec2 tc_offset[9]; 


void main(void) 


{ 
vec4 sample[9]; 
for (int i = 0; i < 9; i++) 
{ 
sample[i] = texture2D(samplerd, 
gl_TexCoord[®].st + tc_offset[i]); 
} 
// “1-1-1 
i -1 9 -1 
// <|) Save 
gl_FragColor = (sample[4] * 9.0) - 
(sample[®] + sample[1] + sample[2] + 
sample[3] + sample[5] + 
sample[6] + sample[7] + sample[8]); 
} 


All our image processing low-level shaders look the same up to and including the part 
where they perform the texture lookups, so we’ll concentrate on the parts that are differ- 
ent: the application of the convolution kernel. The low-level code for sharpening is as 
follows: 


| 1ARBfp1. 
# sharpen.fp 


# 
# 3x3 sharpen kernel 


Image Processing 


ADD tc0, tc, -tc8; 
MAD oPrC, tc4, 9.0, tcQ; 


END 


Notice how this kernel also sums to 1, as did the blur filter. This operation guarantees 
that, on average, the filter is not increasing or decreasing the brightness. It’s just sharpen- 
ing the brightness, as desired. 


Dilation and Erosion 

Dilation and erosion are morphological filters, meaning they alter the shape of objects. 
Dilation grows the size of bright objects, whereas erosion shrinks the size of bright objects. 
(They each have the reverse effect on dark objects.) Figures 23.7 and 23.8 show the effects 
of three passes of dilation and erosion, respectively. 


SS Image Processing Demo 


FIGURE 23.7 This fragment shader dilates objects. 
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Dilation simply finds the maximum value in the neighborhood: 


// dilation.fs 


// 


// maximum of 3x3 kernel 


uniform sampler2D samplerQ; 
uniform vec2 tc_offset[9]; 


void main(void) 


{ 


vec4 sample[9]; 
vec4 maxValue = vec4(0.0); 


for (int i = 0; i < 9; itt) 


{ 
sample[i] = texture2D(sampler®Q, 
gl_TexCoord[0].st + tc_offset[i]); 
maxValue = max(sample[i], maxValue) ; 
} 


gl_FragColor = maxValue; 


| LARBfp1.0 


# dilation. fp 


# 


# maximum of 3x3 kernel 


MAX 
MAX 
MAX 
MAX 
MAX 
MAX 
MAX 
MAX 


END 


tc0, tc, tcl; 
tc0, tc0;. tc2; 
tc0, tc, tc3; 
tc®, tc0, tc4; 
tc®, tc, tc5; 
tc0, tc®@, tcé6; 
tcO, tc®, tc7; 
oPrC, tc®, tc8; 


Erosion conversely finds the minimum value in the neighborhood: 


// erosion.fs 


// 


// minimum of 3x3 kernel 


uniform sampler2D samplerQ; 
uniform vec2 tc_offset[9]; 


void main(void) 


{ 
vec4 sample[9]; 
vec4 minValue = vec4(1.Q); 
for (int i = 0; i < 9; i++) 
{ 
sample[i] = texture2D(samplerd, 
gl_TexCoord[®].st + tc_offset[i]); 
minValue = min(sample[i], minValue) ; 
} 
gl_FragColor = minValue; 
} 
!!ARBfp1.0 


# erosion.fp 


# 


# minimum of 3x3 kernel 


MIN 
MIN 
MIN 
MIN 
MIN 
MIN 
MIN 
MIN 


END 


tc®, tc, tc1; 
tc®@, tc, tc2; 
tc®, tc, tc3; 
tc®, tc, tc4; 
tc®, tc®, tc5; 
tc®, tc, tcé6; 
tc®, tc®, tc7; 
oPrc, tc0, tc8; 
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SS Image Processing Demo 


FIGURE 23.8 This fragment shader erodes objects. 


Edge Detection 


One last filter class worthy of mention here is edge detectors. They do just what you 
would expect—detect edges. Edges are simply places in an image where the color changes 
rapidly, and edge detection filters pick up on these rapid changes and highlight them. 


Three widely used edge detectors are Laplacian, Sobel, and Prewitt. Sobel and Prewitt are 
gradient filters that detect changes in the first derivative of each color channel’s intensity, 
but only in a single direction. Laplacian, on the other hand, detects zero-crossings of the 
second derivative, where the intensity gradient suddenly changes from getting darker to 
getting lighter, or vice versa. It works for edges of any orientation. 


Because the differences in their results are subtle, Figure 23.9 shows the results from only 
one of them, the Laplacian filter. Try out the others and examine their shaders at your 
leisure in the accompanying sample code. 


Image Processing 


[3 image Processing Demo 


FIGURE 23.9 This fragment shader implements Laplacian edge detection. 


The Laplacian’s filter code is almost identical to the sharpen code we just looked at: 


// laplacian.fs 
// 
// Laplacian edge detection 


uniform sampler2D samplerQ; 
uniform vec2 tc_offset[9]; 


void main(void) 


{ 


vec4 sample[9]; 


for (int i = 0; i < 9; i++) 
{ 
sample[i] = texture2D(sampler®Q, 
gl_TexCoord[®].st + tc_offset[i]); 
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[ff 1h 
// -1 8-1 
// -1 -1 -1 


gl_FragColor = (sample[4] * 8.0) - 
(sample[®] + sample[1] + sample[2] + 
sample[3] + sample[5] + 
sample[6] + sample[7] + sample[8]); 


!!ARBfp1.® 
# laplacian.fp 


# 
# Laplacian edge detection 


ee 
ch tit 
ae 


ADD tc0, tc, -tc6; 
ADD tc®, tc, -tc7; 
ADD tc®, tc, -tc8; 
MAD oPrC, tc4, 8.0, tcQ; 


END 


The difference, of course, is that the center kernel value is 8 rather than the 9 present in 
the sharpen kernel. The coefficients sum up to 0 rather than 1. This explains the blackness 
of the image. Instead of, on average, retaining its original brightness, the edge detection 
kernel will produce 0 in areas of the image with no color change. 


Lighting 
Welcome back to another discussion of lighting shaders. In the preceding chapter, we 
covered per-vertex lighting. We also described a couple of per-fragment fixed functionality 


Lighting 


tricks to improve the per-vertex results: separate specular with color sum and power func- 
tion texture for specular exponent. In this chapter, we perform all our lighting calculations 
in the fragment shader to obtain the greatest accuracy. 


The shaders here will look very familiar. The same lighting equations are implemented, so 
the code is virtually identical. One new thing is the use of vertex shaders and fragment 
shaders together. The vertex shader sets up the data that needs to be interpolated across 
the line or triangle, such as normals and light vectors. The fragment shader then proceeds 
to do most of the work, resulting in a final color. 


Diffuse Lighting 
As a refresher, the equation for diffuse lighting follows: 


Cog = Max{N ¢L, O}*C*C, 


diff 


You need a vertex shader that generates both normal and light vectors. Listings 23.13 and 
23.14 contain the high-level and low-level vertex shader source to generate these neces- 
sary interpolants for diffuse lighting. 


LISTING 23.13 Diffuse Lighting Interpolant Generating High-Level Vertex Shader 


// diffuse.vs 
// 
// setup interpolants for diffuse lighting 


uniform vec3 lightPos0; 
varying vec3 N, L; 


void main(void) 
{ 
// vertex MVP transform 
// eye-space normal 
N = gl_NormalMatrix * gl_Normal; 


// eye-space light vector 
vec4 V = gl_ModelViewMatrix * gl_ Vertex; 
L = lightPos® - V.xyz; 


// Copy the primary color 
gl_FrontColor = gl Color; 
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LISTING 23.14 Diffuse Lighting Interpolant Generating Low-Level Vertex Shader 


| !ARBvp1.0 


# diffuse.vp 
# 
# setup interpolants for diffuse lighting 


ATTRIB iPos = vertex.position; # input position 
ATTRIB iPrC = vertex.color.primary; # input primary color 
ATTRIB iNrm = vertex.normal; # input normal 


OUTPUT oPos = result.position; 
OUTPUT oPrC = result.color.primary; 
OUTPUT oTC® = result.texcoord[Q]; 
OUTPUT oTC1 = result.texcoord[1]; 


output position 
output primary color 
output texcoord @ 
output texcoord 1 


PARAM mvp[4] = { state.matrix.mvp }; # model-view * projection matrix 
PARAM mv[4] = { state.matrix.modelview }; # model-view matrix 

# inverse transpose of model-view matrix: 

PARAM mvIT[4] = { state.matrix.modelview.invtrans }; 


PARAM lightPos = program. local[Q]; # light pos in eye space 


TEMP V; # temporary register 


DP4 oPos.x, iPos, mvp[Q]; # xform input pos by MVP 
DP4 oPos.y, iPos, mvp[1]; 
DP4 oPos.z, iPos, mvp[2]; 
DP4 oPos.w, iPos, mvp[3]; 


DP4 V.x, iPos, mv[Q]; # xform input pos by MV 
DP4 V.y, iPos, mv[1]; 
DP4 V.z, iPos, mv[2]; 
DP4 V.w, iPos, mv[3]; 


DP3 oTCO.x, iNrm, mvIT[O]; # xform norm to eye space 
DP3 oTC@.y, iNrm, mvIT[1]; 
DP3 oTC@.z, iNrm, mvIT[2]; # put N in texcoord @ 


SUB oTC1, lightPos, V; # light vector in texcoord 1 


Lighting 


LISTING 23.14 Continued 


MOV oPrC, iPrc; # copy primary color in to out 


END 


When using low-level shaders, we’re stuck tossing the normal and light vector into a stan- 
dard texture coordinate for interpolation. However, notice how we are able to give descrip- 
tive names N and L to our interpolants, known as varyings in GLSL. They have to match 
the names used in the fragment shader. All in all, this feature makes the high-level shaders 
much more readable and less error-prone. For example, if we’re not careful in the low-level 
shaders, we might accidentally output L into texture coordinate 0, whereas the fragment 
shader is expecting it in texture coordinate 1. No compile error would be thrown. GLSL, 
on the other hand, matches them up automatically by name, keeping us out of trouble 
and at the same time avoiding the need for tedious comments in code explaining the 
contents of each interpolant. 


The diffuse lighting fragment shaders resulting in Figure 23.10 follow in Listings 23.15 and 
23.16. Unlike colors produced by specular lighting, diffuse lit colors do not change rapidly 
across a line or triangle, so you will probably not be able to distinguish between per-vertex 
and per-fragment diffuse lighting. For this reason, in general, it would be more efficient to 
perform diffuse lighting in the vertex shader, as we did in the preceding chapter. We 
perform it here per-fragment simply as a learning exercise. 


LISTING 23.15 Diffuse Lighting High-Level Fragment Shader 


// diffuse.fs 
// 
// per-pixel diffuse lighting 


varying vec3 N, L; 


void main(void) 
{ 
// output the diffuse color 
float intensity = max(0.0, 
dot(normalize(N), normalize(L))); 


gl_FragColor = gl Color; 
gl_FragColor.rgb *= intensity; 
} 


EEE 
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3 Lighting Demo 


FIGURE 23.10 Per-fragment diffuse lighting. 


LISTING 23.16 Diffuse Lighting Low-Level Fragment Shader 


!!ARBfp1.0 


# diffuse.fp 
# 
# per-pixel diffuse lighting 


ATTRIB iPrC = fragment.color.primary;# 


i} 


ATTRIB iTC@ = fragment.texcoord[0]; 
ATTRIB iTC1 = fragment.texcoord[1]; 


OUTPUT oPrc 


ll 


result.color; 
TEMP N, L, NdotL; 
DP3 N.w, iTC@, iTCQ; 


RSQ N.w, N.w; 
MUL N, iTC@, N.w; 


# 
# 


input primary color 
normal (N) 
light vector (L) 


output color 


normalize normal 


Lighting 


LISTING 23.16 Continued 


DP3 L.w, iTC1, iTC1; # normalize light vec 
RSQ L.w, L.w; 
MUL L, iTC1, L.w; 


DP3 NdotL, N, L; # ON. E 

MAX NdotL, NdotL, 0.0; # max(N .L, Q) 

MUL oPrC.rgb, iPrC, NdotL; # diffuse color 

MOV oPrC.a, iPrC.a; # preserve alpha 
END 


First, we normalize the interpolated normal and light vectors. Then one more dot product, 
a maximum, and a multiply, and we're finished. Because we want a white light, we can 
save ourselves the additional multiply by C, = {1,1,1,1}. 


Multiple Specular Lights 
Rather than cover specular lighting and multiple light samples independently, we’ll cover 
both at the same time. As a refresher, the specular lighting equation is 


Coc Max{N © H, 0}45,*C,.. * C, 


The vertex shaders need to generate light vector interpolants for all three lights, in addi- 
tion to the normal vector. We’ll calculate the half-angle vector in the fragment shader. 
Listings 23.17 and 23.18 show the vertex shaders for the three diffuse and specular lights. 


LISTING 23.17 Three Lights High-Level Vertex Shader 


// 3lights.vs 
// 
// setup interpolants for 3 specular lights 


uniform vec3 lightPos®; 
uniform vec3 lightPos1; 
uniform vec3 lightPos2; 
varying vec3 N, L[3]; 


void main(void) 
{ 
// vertex MVP transform 
gl_Position = gl_ModelViewProjectionMatrix * gl Vertex; 
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// eye-space normal 
N = gl_NormalMatrix * gl_ Normal; 


// Light vectors 


L[0] 
L[1] 
L[2] 


lightPosd 
lightPos1 
lightPos2 


- V.xyZ; 
- V.xyZ; 
- V.xXyZ; 


// Copy the primary color 
gl_FrontColor = 


gl_Color; 


vec4 V = gl ModelViewMatrix * gl Vertex; 


LISTING 23.18 Three Lights Low-Level Vertex Shader 


! !ARBvp1.® 


# 3lights.vp 


# 


# setup interpolants 


ATTRIB 
ATTRIB 
ATTRIB 


OUTPUT 
OUTPUT 
OUTPUT 
OUTPUT 
OUTPUT 
OUTPUT 


iPos 
iPrc 
iNrm 


oPos 
oPrc 
oTca 
oTc1 
oTCc2 
oTCc3 


= vertex. 
= vertex. 
= vertex. 


= result. 
= result. 
= result. 
= result. 
= result. 
= result. 


for 3 specular lights 


position; 


# input position 


color.primary; # input primary color 


normal; 


position; 


color.primary; 


texcoord[0]; 
texcoord[1]; 
texcoord[2]; 
texcoord[3]; 


PARAM mvp[4] = { state.matrix.mvp 


PARAM mv[4] = 


# input normal 


output position 
output primary color 
output texcoord 0 
output texcoord 1 
output texcoord 2 
output texcoord 3 


Sb th HR HR HR RK 


}; # model-view * projection matrix 


{ state.matrix.modelview }; # model-view matrix 


# inverse transpose of model-view matrix: 
PARAM mvIT[4] = { state.matrix.modelview.invtrans }; 


LISTING 23.18 Continued 


PARAM LightPos® 
PARAM lightPos1 
PARAM lightPos2 


program. local[Q]; 
program. local[1]; 
program. local[2]; 


TEMP V; 


DP4 
DP4 
DP4 
DP4 


DP4 
DP4 
pP4 
pP4 
DP3 
DPS 
DPS 
SUB 
SUB 
SUB 


MOV 


END 


oPos.x, iPos, mvp[Q]; 
oPos.y, iPos, mvp[1]; 
oPos.z, iPos, mvp[2]; 
oPos.w, iPos, mvp[3]; 


V.x, iPos, mv[0]; 

V.y, iPos, mv[1]; 

V.z, iPos, mv[2]; 

V.w, iPos, mv[3]; 
oTC®.x, iNrm, mvIT[O]; 
oTC®.y, iNrm, mvIT[1]; 
oTC®.z, iNrm, mvIT[2]; 
oTC1, lightPos®, V; 
oTC2, lightPos1, V; 
oTC3, lightPos2, V; 


oPrC, iPr; 


Lighting 


light pos @ in eye space 
light pos 1 in eye space 
light pos 2 in eye space 


temporary register 


xform input pos by MVP 


xform input pos by MV 


xform norm to eye space 

put N in texcoord 0 

light vector @ in texcoord 1 
light vector 1 in texcoord 2 
light vector 2 in texcoord 3 


copy primary color in to out 


The fragment shaders will be doing most of the heavy lifting. Figure 23.11 shows the 
result of Listings 23.19 and 23.20. 
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3 Lighting Derno 


FIGURE 23.11  Per-fragment diffuse and specular lighting with three lights. 


LISTING 23.19 Three Diffuse and Specular Lights High-Level Fragment Shader 


// 3lights.fs 
// 
// 3 specular lights 


varying vec3 N, L[3]; 


void main(void) 
{ 
const float specularExp = 128.0; 


vec3 NN = normalize(N) ; 


// Light colors 

vec3 lightCol[3]; 

lightCol[@] = vec3(1.0, 0.25, 0.25); 
lightCol[1] = vec3(0.25, 1.0, 0.25); 
lightCol[2] = vec3(0.25, 0.25, 1.0); 


LISTING 23.19 Continued 


Lighting 


gl_FragColor 


= vec4(@.0); 


for (int 1.= 0; 1-< 13; it+) 


{ 


vec3 NL 
vec3 NH 


normalize(L[i]); 


normalize(NL + vec3(@.0, @.@, 1.0)); 


// Accumulate the diffuse contributions 
gl_FragColor.rgb += gl_Color.rgb * lightCol[i] * 
max(@.@, dot(NN, NL)); 


// Accumulate the specular contributions 
gl_FragColor.rgb += lightCol[i] * 


pow(max(@.@, dot(NN, NH)), specularExp); 


gl_FragColor.a = gl Color.a; 


LISTING 23.20 Three Diffuse and Specular Lights Low-Level Fragment Shader 


!!ARBfp1.0 


# 8lights.fp 


# 


# 3 specular lights 


ATTRIB 
ATTRIB 
ATTRIB 
ATTRIB 
ATTRIB 


OUTPUT 


PARAM lightCol0 
PARAM lightCol1 
PARAM lightCol2 


iPrc 
iTCO 
iTC1 
iTc2 
iTC3 


oPrc 


fragment.color.primary;# input primary color 


fra 
fra 
fra 
fra 


res 


gment.texcoord[Q]; 
gment.texcoord[1]; 
gment.texcoord[2]; 
gment.texcoord[3]; 


ult.color; 
{, 1.105. 0525, 0.25; 


{ 0.25, 1.0, 0.25, 
{ 0.25, 0.25, 1.0, 


# normal (N) 

# light vector 
# light vector 
# light vector 


# output color 
1.0 }; # light 


1.0 }; # light 
1.0 }; # light 


TEMP N, L, H, NdotL, NdotH, finalColor; 
ALIAS diffuse = NdotL; 


ALIAS specular 


NdotH; 


(L) 0 
(L) 1 
(L) 2 


® color 
1 color 
2 color 
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DP3 
RSQ 
MUL 


DP3 
RSQ 
MUL 


ADD 
DP3 
RSQ 
MUL 


DP3 
MAX 
MUL 
MUL 


DP3 
MAX 
POW 
MAD 


DP3 
RSQ 
MUL 


ADD 
DP3 
RSQ 
MUL 


DP3 
MAX 
MUL 
MAD 


DP3 
MAX 
POW 
MAD 


N.w, iTCO, iTCQ; 
N.w, N.w; 
N, iTCQ, N.w; 


L.w, iTC1, iTC1; 
L.w, L.w; 
L, iTC1, L.w; 


H, L, {0, ®, 1}; 
H.w, H, H; 
H.w, H.w; 
H, H, H.w; 


NdotL, N, L; 

NdotL, NdotL, 0.0; 

diffuse, iPrC, NdotL; 
finalColor, diffuse, lightCol0; 


NdotH, N, H; 

NdotH, NdotH, 0.0; 

specular, NdotH.x, 128.0.x; 
finalColor, specular, lightCol®d, 


L.w, iTC2, iTC2; 
L.w, L.w; 
L; 47e2, L.w; 


H, L, {0, 0, 1}; 
H.w, H, H; 
H.w, H.w; 
H, H, H.w; 


NdotL, N, L; 
NdotL, NdotL, 0.0; 
diffuse, iPrC, NdotL; 


# normalize normal 


# normalize light vec 0 


# half-angle vector 0 
# normalize it 


#N . LO 
max(N . L, Q) 
# diffuse color 


a 


#N . HO 

# max(N . H, @) 
# NdotH*128 
finalColor; 


# normalize light vec 1 


# half-angle vector 1 
# normalize it 


#N. U1 
# max(N. L, 0) 
# diffuse color 


finalColor, diffuse, lightCol1, finalColor; 


NdotH, N, H; 

NdotH, NdotH, 0.0; 

specular, NdotH.x, 128.0.x; 
finalColor, specular, lightCol1, 


#N .H1 

# max(N . H, Q) 
# NdotH*128 
finalColor; 


Procedural Texture Mapping 


LISTING 23.20 Continued 


DP3 L.w, iTC3, iTC3; # normalize light vec 2 
RSQ L.w, L.w; 
MUL L, iTC3, L.w; 


ADD H, L, {@, 0, 1}; # half-angle vector 2 
DP3 H.w, H, H; # normalize it 

RSQ H.w, H.w; 

MUL H, H, H.w; 

DP3 NdotL, N, L; #iN .xk2 

MAX NdotL, NdotL, 0.0; # max(N .L, Q) 

MUL diffuse, iPrC, NdotL; # diffuse color 


MAD finalColor, diffuse, lightCol2, finalColor; 


DP3 NdotH, N, H; #N. H2 

MAX NdotH, NdotH, 0.0; # max(N . 4H, Q) 
POW specular, NdotH.x, 128.0.x; # NdotH*128 

MAD oPrC.rgb, specular, lightCol2, finalColor; 

MOV oPrC.a, iPrC.a; # preserve alpha 
END 


This time, we made each of the three lights a different color instead of white, necessitating 
an additional multiply by lightColn (C,). The lack of loops really makes itself obvious 
here in the low-level shader, which is more than three times as long. 


Procedural Texture Mapping 


When can you texture map an object without using any textures? When you’re using 
procedural texture maps. This technique enables you to apply colors or other surface prop- 
erties to an object, just like using conventional texture maps. With conventional texture 
maps, you load a texture image into OpenGL with glTexImage; then you perform a texture 
lookup within your fragment shader. However, with procedural texture mapping, you skip 
the texture loading and texture lookup and instead describe algorithmically what the 
texture looks like. 


Procedural texture mapping has advantages and disadvantages. One advantage is that its 
storage requirements are measured in terms of a few shader instructions rather than 
megabytes of texture cache and/or system memory consumed by conventional textures. 
This frees your storage for other uses, such as the vertex buffer objects discussed in 
Chapter 16, “Buffer Objects: It’s Your Video Memory; You Manage It!” 
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Another benefit is its virtually limitless resolution. Like vector drawings versus raster draw- 
ings, procedural textures scale to any size without loss of quality. Conventional textures 
require you to increase texture image sizes to improve quality when greatly magnified. 
Eventually, you’ll hit a hardware limit. The only hardware limit affecting procedural 
texture quality is the floating-point precision of the shader processors, which are required 
to be at least 24-bit for OpenGL. 


A disadvantage of procedural texture maps, and the reason they’re not used more 
frequently, is that the complexity of the texture you want to represent requires an equally 
complex fragment shader. Everything from simple shapes and colors all the way to 
complex plasma, fire, smoke, marble, or wood grain can be achieved with procedural 
textures, given enough shader instructions to work with. But sometimes you just want the 
company logo or a satellite map or someone’s face textured onto your scene. Certainly, 
conventional textures will always serve a purpose! 


Checkerboard Texture 

Enough discussion. Let’s warm up with our first procedural texture: a 3D checkerboard. 
Our object will appear to be cut out of a block of alternating white and black cubes. 
Sounds simple enough, right? 


We’ll use the object-space position at each fragment to decide what color to make that 
fragment. So we need a vertex shader that, in addition to transforming the object-space 
position to clip-space as usual, also copies that object-space position into an interpolant so 
it becomes available to the fragment shader. While we’re at it, we might as well add diffuse 
and specular lighting, so our vertex shader needs to output the normal and light vector as 
well. 


Listings 23.21 and 23.22 show the high-level and low-level versions of this vertex shader. 
We'll use it for all three of our procedural texture mapping samples. 


LISTING 23.21 Procedural Texture Mapping High-Level Vertex Shader 


// checkerboard.vs 

// 

// Generic vertex transformation, 

// copy object-space position and 

// lighting vectors out to interpolants 


uniform vec3 lightPos; 


varying vec3 N, L, V; 


void main(void) 


{ 


Procedural Texture Mapping 


LISTING 23.21 Continued 


// normal MVP transform 
gl_Position = gl ModelViewProjectionMatrix * gl _ Vertex; 


// map object-space position onto unit sphere 
V = gl_Vertex.xyz; 


// eye-space normal 
N = gl_NormalMatrix * gl_Normal; 


// eye-space light vector 
vec4 Veye = gl ModelViewMatrix * gl Vertex; 
L = lightPos - Veye.xyz; 


LISTING 23.22 Procedural Texture Mapping Low-Level Vertex Shader 
!1ARBvp1.0 


# checkerboard.vp 

# 

# Generic vertex transformation, 

# copy object-space position and 

# light vectors out to interpolants 


ATTRIB iPos = vertex.position; # input position 
ATTRIB iNrm = vertex.normal; # input normal 


OUTPUT oPos = result.position; 

OUTPUT oTC® = result.texcoord[®]; 
OUTPUT oTC1 = result.texcoord[1]; 
OUTPUT oTC2 = result.texcoord[2]; 


output position 

output texcoord @: N 
output texcoord 1: L 
output texcoord 2: V 


* Rt tt 


PARAM mvp[4] = { state.matrix.mvp }; # model-view * proj matrix 
PARAM mv[4] = { state.matrix.modelview }; # model-view matrix 
# inverse transpose of model-view matrix: 

PARAM mvIT[4] = { state.matrix.modelview.invtrans }; 


PARAM lightPos = program.local[@]; # light pos in eye space 


TEMP V; # temporary register 
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LISTING 23.22 Continued 


DP4 oPos.x, iPos, mvp[Q0]; # xform input pos by MVP 
DP4 oPos.y, iPos, mvp[1]; 
DP4 oPos.z, iPos, mvp[2]; 
DP4 oPos.w, iPos, mvp[3]; 


DP4 V.x, iPos, mv[0]; # xform input pos by MV 
DP4 V.y, iPos, mv[1]; 
DP4 V.z, iPos, mv[2]; 
DP4 V.w, iPos, mv[3]; 


DP3 oTC@.x, iNrm, mvIT[Q]; # xform norm to eye space 
DP3 oTCO@.y, iNrm, mvIT[1]; 

DP3 oTC@.z, iNrm, mvIT[2]; # put N in texcoord @ 

SUB oTC1, lightPos, V; # light vector in texcoord 1 
MOV oTC2, iPos; # put objPos in texcoord 2 
END 


The object we’re using for our samples is a sphere. The size of the sphere doesn’t matter 
because we normalize the object-space position at the beginning of the fragment shader. 
This means that all the positions we deal with in the fragment shader will be in the range 
[-1,1]. 


Our strategy for the fragment shader will be to break up the range [-1,1] into eight alter- 
nating blocks along each axis. Each block will be assigned an alternating value of 0 or 1 
for each axis, as illustrated in Figure 23.12. If the total of the three values is even, we paint 
it black; otherwise, we paint it white. 


FIGURE 23.12 This diagram illustrates how we assign alternating colors to blocks of frag- 
ments. 


Procedural Texture Mapping 


Figure 23.13 shows the result of Listings 23.23 and 23.24, which implement our checker- 


board procedural texture mapping algorithm. 


Lighting Demo 


FIGURE 23.13 This 3D checkerboard is generated without using any texture images. 


LISTING 23.23 Checkerboard High-Level Fragment Shader 


// checkerboard.fs 
// 
// 3D solid checker grid 


varying vec3 V; // object-space position 
varying vec3 N; // eye-space normal 
varying vec3 L; // eye-space light vector 


const vec3 onColor = vec3(1.0, 1.0, 1.0); 
const vec3 offColor = vec3(0.0, 0.0, 0.0); 


const float ambientLighting = 0.2; 
const float specularExp = 60.0; 


const float specularIntensity = 0.75; 


const int numSquaresPerSide = 8; 


1087 


€Z 


1088 


CHAPTER 23 Fragment Shading: Empower Your Pixel Processing 


LISTING 23.23 Continued 


void main (void) 
{ 
// Normalize vectors 
vec3 NN = normalize(N); 
vec3 NL = normalize(L); 
vec3 NV = normalize(V); 
vec3 NH = normalize(NL + vec3(0.0, @.0, 1.0)); 


// Map -1,1 to ®,numSquaresPerSide 
vec3 onOrOff = ((NV + 1.0) * float(numSquaresPerSide)) / 2.0; 
// mod 2 >= 1 
onoOroff = step(1.0, mod(onOroff, 2.0)); 
// 3-way xor 
onoroff.x = step(@.5, 
mod(onOrOff.x + onOrOff.y + onOrOff.z, 2.0)); 


// checkerboard grid 
vec3 surfColor = mix(offColor, onColor, onOrOff.x); 


// calculate diffuse lighting + 20% ambient 
surfColor *= (ambientLighting + vec3(max(@.@, dot(NN, NL)))); 


// calculate specular lighting w/ 75% intensity 
surfColor += (specularIntensity * 


vec3(pow(max(@.@, dot(NN, NH)), specularExp))); 


gl_FragColor = vec4(surfColor, 1.0); 


LISTING 23.24 Checkerboard Low-Level Fragment Shader 
!!ARBfp1.0 


# checkerboard. fp 
# 
# 3D solid checker grid 


ATTRIB N = fragment.texcoord[Q]; 
ATTRIB L = fragment.texcoord[1]; 
ATTRIB V = fragment.texcoord[2]; # obj-space position 


Procedural Texture Mapping 


LISTING 23.24 Continued 
OUTPUT oPrC = result.color; # output color 


PARAM onColor = {1.0, 1.0, 1.0, 1.0}; 
PARAM offColor = {@.0, 0.0, 0.0, 1.0}; 


# @.25 * squares per side, ambient lighting, 
# specular exponent, specular intensity 
PARAM misc = {2.0, 0.2, 60.0, 0.75}; 


TEMP NV, NN, NL, NH, NdotL, NdotH, surfColor, onOrOff; 
ALIAS specular = NdothH; 


DP3 NV.w, V, V; # normalize vertex pos 
RSQ NV.w, NV.w; 
MUL NV, V, NV.w; 


# Map position from -1,1 to ®,numSquaresPerSide/2 

MAD onOrOff, NV, misc.x, misc.x; 

# mod2 by doubling FRC, then subtract 1 for >= 1 compare 
FRC onOrOff, onOroff; 

MAD onOrOff, onOrOff, 2.0, -1.0; 

CMP onOrOff, onOrOff, 0.0, 1.0; 


# perform xor by adding all 3 axes' onoroff values, 
# then mod2 again 

DP3 onOrOff, onOrOff, 1.0; 

MUL onOrOff, onOrOff, 0.5; 

FRC onOrOff, onOroff; 

MAD onOrOff, onOrOff, 2.0, -1.0; 

CMP onOrOff, onOrOff, 0.0, 1.0; 


# checkerboard grid 
LRP surfColor, onOrOff, onColor, offColor; 


DP3 NN.w, N, N; # normalize normal 
RSQ NN.w, NN.w; 
MUL NN, N, NN.w; 


DP3 NL.w, L, L; # normalize light vec 
RSQ NL.w, NL.w; 
MUL NL, L, NL.w; 
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LISTING 23.24 Continued 


ADD NH, NL, {@, 0, 1}; # half-angle vector 
DP3 NH.w, NH, NH; # normalize it 

RSQ NH.w, NH.w; 

MUL NH, NH, NH.w; 


# diffuse lighting 

DP3 NdotL, NN, NL; #N.L 

MAX NdotL, NdotL, 0.0; # max(N . L, Q) 

ADD NdotL, NdotL, misc.y; # 20% ambient 

MUL surfColor, surfColor, NdotL; # factor in diffuse color 


# specular lighting 


DP3 NdotH, NN, NH; #N.H 

MAX NdotH, NdotH, 0.0; # max(N . H, @) 

POW specular, NdotH.x, misc.z; # NdotH*60 

MAD oPrC, misc.w, specular, surfColor; # 75% specular intensity 


END 


GLSL has a built-in modulo function (mod), which is used to achieve the alternating 
blocks. However, we have to work a little harder to perform the modulo 2 operation in our 
low-level fragment shader. We take the value, divide it by 2, use the FRC instruction to get 
the fractional part, and then multiply that by 2. What we’re left with is a value in the 
range [0,2]. 


Next, we must determine whether the value is within [0,1] or [1,2]. We do this in GLSL 
using the step function, which returns 1 if the second argument is greater than or equal 
to the first, and 0 otherwise. In the low-level shader, we can do this using the CMP instruc- 
tion, but because it compares the first argument to 0, not 1, we first subtract 1 from the 
argument. 


Now that we have a value of 0 or 1 on each axis, we sum those three values and again 

perform modulo 2 and a greater than or equal to comparison. That way, we can assign 

colors of black or white based on whether the final sum is even or odd. We accomplish 
this with mix in the high-level shader or LRP in the low-level version. 


You can very easily alter the shaders to change the checkerboard colors or to adjust the 
number of blocks per row. Give it a try! 


Procedural Texture Mapping 


Beach Ball Texture 


In this next sample, we’re going to turn our sphere into a beach ball. The ball will have 
eight longitudinal stripes with alternating primary colors. The north and south poles of 
the ball will be painted white. Let’s get started! 


Look at the ball from above. We’ll be slicing it up into three half spaces: north-south, 
northeast-southwest, and northwest-southeast. See Figure 23.14 for a visual depiction. The 
north slices are assigned full red values, while south slices are assigned no red. The two 
slices that are both in the southeast half space and the northeast half space are assigned 
full green, while all other slices receive no green. Notice how the overlapping red and 
green slice becomes yellow. Finally, all slices in the southwest half space are assigned the 
color blue. 


FIGURE 23.14 An overhead view showing how the beachball colors are assigned. 


The east slices nicely alternate from red to yellow to green to blue. But what about the 
west slices? The easiest way to address them is to effectively copy the east slices and rotate 
them 180 degrees. We’re looking down at the ball from the positive y-axis. If the object- 
space position’s x coordinate is greater than or equal to 0, the position is used as-is. 
However, if the coordinate is less than 0, we negate both the x-axis and z-axis position, 
which maps the original position to its mirror on the opposite side of the beach ball. 


The white caps at the poles are simple to add in. After coloring the rest of the ball with 
stripes, we replace that color with white whenever the absolute value of the y-axis position 
is close to 1. Figure 23.15 shows the result of the beach ball shaders in Listings 23.25 and 
23.26. 
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3 Lighting Demo 


FIGURE 23.15 You have built your own beach ball from scratch! 


LISTING 23.25 Beach Ball High-Level Fragment Shader ; 


// beachball.fs 
// 
// Longitudinal stripes, end caps 


varying vec3 V; // object-space position 
varying vec3 N; // eye-space normal 
varying vec3 L; // eye-space light vector 


const vec3 myRed = vec3(1.0, 0.0, 0.0); 
const vec3 myYellow = vec3(1.0, 1.0, 0.0); 
const vec3 myGreen = vec3(0.0, 1.0, 0.0); 
const vec3 myBlue = vec3(0.0, 0.0, 1.0); 
const vec3 myWhite = vec3(1.0, 1.0, 1.0); 
const vec3 myBlack = vec3(0.0, 0.0, 0.0); 


Procedural Texture Mapping 


LISTING 23.25 Continued 


const vec3 northHalfSpace = vec3(0.0, 0.0, 1.0); 
const vec3 northeastHalfSpace = vec3(@.707, 0.0, 0.707); 
const vec3 northwestHalfSpace = vec3(-0.707, 0.0, 0.707); 


const float capSize = 0.03; // ®@ to 1 
const float smoothEdgeTol = 0.005; 

const float ambientLighting = 0.2; 

const float specularExp = 60.0; 

const float specularIntensity = 0.75; 


void main (void) 


{ 


// Normalize vectors 


vec3 NN = normalize(N); 
vec3 NL = normalize(L); 
vec3 NH = normalize(NL + vec3(0.0, 0.0, 1.0)); 
vec3 NV = normalize(V); 


// Mirror half of ball across X and Z axes 
float mirror = (NV.x >= 0.0) ? 1.0: -1.0; 
NV.xz *= mirror; 


// Check for north/south, east/west, 

// northeast/southwest, northwest/southeast 
vec4 distance; 

distance.x = dot(NV, northHalfSpace) ; 
distance.y = dot(NV, northeastHalfSpace) ; 
distance.z = dot(NV, northwestHalfSpace) ; 


// setup for white caps on top and bottom 
distance.w = abs(NV.y) - 1.0 + capSize; 


distance = smoothstep(vec4(0.0), vec4(smoothEdgeTol), distance) ; 


// red, green, red+green=yellow, and blue stripes 

vec3 surfColor = mix(myBlack, myRed, distance.x) ; 

surfColor += mix(myBlack, myGreen, distance.y*(1.@-distance.z)); 
surfColor = mix(surfColor, myBlue, 1.@-distance.y) ; 


// white caps on top and bottom 
surfColor = mix(surfColor, myWhite, distance.w) ; 
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LISTING 23.25 Continued 
// calculate diffuse lighting + 20% ambient 


surfColor *= (ambientLighting + vec3(max(@.0, dot(NN, NL)))); 


// calculate specular lighting w/ 75% intensity 
surfColor += (specularIntensity * 
vec3(pow(max(@.@, dot(NN, NH)), specularExp))); 


gl_FragColor = vec4(surfColor, 1.0); 


LISTING 23.26 Beach Ball Low-Level Fragment Shader 
L!ARBfp1.@ 


# beachball.fp 
# 
# Longitudinal stripes, end caps 


ATTRIB N = fragment.texcoord[Q]; 

ATTRIB L = fragment.texcoord[1]; 

ATTRIB V = fragment.texcoord[2]; # obj-space position 
OUTPUT oPrC = result.color; # output color 


PARAM myRed = {1.0, 0.0, 0.0, 1.0}; 
PARAM myYellow = {1.0, 1.0, 0.0, 1.0}; 
PARAM myGreen = {@.0, 1.0, 0.0, 1.0}; 
PARAM myBlue = {0@.0, 0.0, 1.0, 1.0}; 
PARAM myWhite = {1.0, 1.0, 1.0, 1.0}; 
PARAM myBlack = {0.0, 0.0, 0.0, 1.0}; 


PARAM northHalfSpace = {@.0, 0.0, 1.0}; 
PARAM northeastHalfSpace = {0.707, 0.0, 0.707}; 
PARAM northwestHalfSpace = {-0.707, 0.0, 0.707}; 


# cap size minus one, ambient lighting, 
# specular exponent, specular intensity 
PARAM misc = {-@.97, @.2, 60.0, 0.75}; 


TEMP NV, NN, NL, NH, NdotL, NdotH, surfColor, distance, mirror; 


ALIAS specular = NdotH; 
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LISTING 23.26 Continued 
ALIAS redColor = NV; 


DP3 NV.w, V, V; # normalize vertex pos 
RSQ NV.w, NV.w; 
MUL NV, V, NV.w; 


# Mirror half of ball across X and Z axes 
CMP mirror, NV.x, -1.0, 1.0; 
MUL NV.xz, NV, mirror; 


£Z 


# Check for north/south, east/west, 

# northeast/southwest, northwest/southeast 
DP3 distance.x, NV, northHalfSpace; 

DP3 distance.y, NV, northeastHalfSpace; 
DP3 distance.z, NV, northwestHalfSpace; 


# setup for white caps on top and bottom 
ABS distance.w, NV.y; 
ADD distance.w, distance.w, misc.x; 


CMP distance, distance, 0.0, 1.0; 


# red, green, red+green=yellow, and blue stripes 
LRP redColor, distance.x, myRed, myBlack; 

MAD distance.z, -distance.y, distance.z, distance.y; 
LRP surfColor, distance.z, myGreen, myBlack; 

ADD surfColor, surfColor, redColor; 

SUB distance.y, 1.0, distance.y; 

LRP surfColor, distance.y, myBlue, surfColor; 


# white caps on top and bottom 
LRP surfColor, distance.w, myWhite, surfColor; 


DP3 NN.w, N, N; # normalize normal 
RSQ NN.w, NN.w; 
MUL NN, N, NN.w; 


DP3 NL.w, L, L; # normalize light vec 
RSQ NL.w, NL.w; 
MUL NL, L, NL.w; 
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LISTING 23.26 : Continued 


ADD NH, NL, {0, 0, 1}; # half-angle vector 
DP3 NH.w, NH, NH; # normalize it 

RSQ NH.w, NH.w; 

MUL NH, NH, NH.w; 


# diffuse lighting 

DP3 NdotL, NN, NL; #°N 400 

MAX NdotL, NdotL, 0.0; # max(N . L, ) 

ADD NdotL, NdotL, misc.y; # 20% ambient 

MUL surfColor, surfColor, NdotL; # factor in diffuse color 


# specular lighting 


DP3 NdotH, NN, NH; #N.H 

MAX NdotH, NdotH, 0.0; # max(N . H, Q) 

POW specular, NdotH.x, misc.z; # NdotH*60 

MAD oPrC, misc.w, specular, surfColor; # 75% specular intensity 


END 


After remapping all negative x positions as described earlier, we use dot products to deter- 
mine on which side of each half space the current object-space coordinate falls. The sign 
of the dot product tells us which side of the half space is in play. In the low-level shader, 
we use the CMP instruction to perform this greater than or equal to 0 comparison. 
However, in the GLSL shader, we don’t use the built-in step function this time. Instead, 
we introduce a new and improved version: smoothstep. 


Instead of transitioning directly from 0 to 1 at the edge of a half space, smoothstep allows 
for a smooth transition near the edge where values between 0 and 1 are returned. Switch 
back and forth between the high-level and low-level versions and you'll see how 
smoothstep helps reduce the aliasing jaggies. 


Toy Ball Texture 

For our final procedural texture mapping feat, we'll transform our sphere into a familiar 
toy ball, again using no conventional texture images. This ball will have a red star on a 
yellow background circumscribed by a blue stripe. We will describe all this inside a frag- 
ment shader. 


Procedural Texture Mapping 


The tricky part is obviously the star shape. For each fragment, the shader must determine 
whether the fragment is within the star, in which case it’s painted red, or whether it 
remains outside the star, in which case it’s painted yellow. To make this determination, we 
first detect whether the fragment is inside or outside five different half spaces, as shown in 
Figure 23.16. 


FIGURE 23.16 This diagram illustrates the determination of whether a fragment is inside or 
outside the star as described by 5 half spaces. 


Any fragment that is inside at least four of the five half spaces is inside the star. We'll start 
a counter at -3 and increment it for every half space that the fragment falls within. Then 
we'll clamp it to the range [0,1]. A 0 indicates that we’re outside the star and should paint 
the fragment yellow. A 1 indicates that we’re inside the star and should paint the frag- 
ment red. 


Adding the blue stripe, like the white caps on the beach ball, is an easy last step. Instead 
of repainting fragments close to the ends of the ball, we repaint them close to the center, 
this time along the z-axis. Figure 23.17 illustrates the result of the toy ball shaders in 
Listings 23.27 and 23.28. 
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FIGURE 23.17 The toy ball shader describes a relatively complex shape. 


LISTING 23.27 Toy Ball High-Level Fragment Shader 


// toyball.fs 
// 
// Based on shader by Bill Licea-Kane 


varying vec3 V; // object-space position 
varying vec3 N; // eye-space normal 
varying vec3 L; // eye-space light vector 


const vec3 myRed = vec3(0.6, 0.0, 0.0); 
const vec3 myYellow = vec3(@.6, 0.5, 0.0); 
const vec3 myBlue = vec3(0.0, 0.3, 0.6); 


const vec3 myHalfSpace® = vec3(0.31, 0.95, 0.0); 
const vec3 myHalfSpace1 = vec3(-0.81, 0.59, 0.0); 
const vec3 myHalfSpace2 = vec3(-0.81, -@.59, 0.0); 
const vec3 myHalfSpace3 = vec3(0.31, -@.95, 0.0); 
const vec3 myHalfSpace4 = vec3(1.0, 0.0, 0.0); 
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LISTING 23.27 Continued 


const float stripeThickness = 0.4; // ® to 1 
const float starSize = 0.2; // 0 to ~0.3 
const float smoothEdgeTol = 0.005; 

const float ambientLighting = 0.2; 

const float specularExp = 60.0; 

const float specularIntensity = 0.5; 


void main (void) 


{ 


1x4 


vec4 distVector; 
float distScalar; 


// Normalize vectors 

vec3 NN = normalize(N); 

vec3 NL = normalize(L); 

vec3 NH = normalize(NL + vec3(0.@, 0.0, 1.0)); 
vec3 NV = normalize(V); 


// Each flat edge of the star defines a half-space. The interior 
// of the star is any point within at least 4 out of 5 of them. 
// Start with -3 so that it takes adding 4 ins to equal 1. 

float myInOut = -3.0; 


// We need to perform 5 dot products, one for each edge of 
// the star. Perform first 4 in vector, 5th in scalar. 


distVector.x = dot(NV, myHalfSpace®) ; 
distVector.y = dot(NV, myHalfSpace1) ; 
distVector.z = dot(NV, myHalfSpace2) ; 
distVector.w = dot(NV, myHalfSpace3) ; 


distScalar = dot(NV, myHalfSpace4) ; 


// The half-space planes all intersect the origin. We must 
// offset them in order to give the star some size. 
distVector += starSize; 

distScalar += starSize; 


distVector = smoothstep(®.@, smoothEdgeTol, distVector) ; 
distScalar = smoothstep(®.0, smoothEdgeTol, distScalar) ; 
myInOut += dot(distVector, vec4(1.0)); 

myInOut += distScalar; 

myInOut = clamp(myInOut, 0.0, 1.0); 
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LISTING 23.27 Continued 


// red star on yellow background 
vec3 surfColor = mix(myYellow, myRed, myInOut) ; 


// blue stripe down middle 
myInOut = smoothstep(0.®, smoothEdgeTol, 


surfColor = 


// calculate 
surfColor *= 


// calculate 
surfColor += 


abs(NV.z) - stripeThickness) ; 


mix(myBlue, surfColor, myInOut); 


diffuse lighting + 20% ambient 
(ambientLighting + vec3(max(®.®, dot(NN, NL)))); 


specular lighting w/ 50% intensity 
(speculariIntensity * 


vec3(pow(max(@.@, dot(NN, NH)), specularexp))); 


gl_FragColor 


= vec4(surfColor, 1.0); 


LISTING 23.28 Toy Ball Low-Level Fragment Shader 


!!ARBfp1.0 


# toyball.fp 
# 


# Based on shader by Bill Licea-Kane 


ATTRIB N 
ATTRIB L 
ATTRIB V 


OUTPUT oPrc 


PARAM myRed 
PARAM myYellow = 


fragment.texcoord[Q]; 
fragment.texcoord[1]; 
fragment.texcoord[2]; # obj-space position 


result.color; # output color 


{0.6, 0.0, 0.0, 1.0}; 


{0.6, 0.5, 0.0, 1.0}; 


PARAM myBlue = {0.0, @.3, 0.6, 1.0}; 


PARAM myHalfSpaced 
PARAM myHalfSpace1 
PARAM myHalfSpace2 
PARAM myHalfSpace3 
PARAM myHalfSpace4 


{0.31, 0.95, 0.0}; 
{-0.81, 0.59, 0.0}; 
{-0.81, -0.59, 0.0}; 
{0.31, -0.95, 0.0}; 
{1.0, 0.0, 0.0}; 
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LISTING 23.28 Continued 


# stripe thickness, star size & ambient lighting, 
# specular exponent, specular intensity 
PARAM misc = {0.4, 0.2, 60.0, 0.5}; 


TEMP NV, NN, NL, NH, NdotL, NdotH, surfColor, distance, myInOut; 
ALIAS specular = NdotH; 


DPS NV.w, V, V; # normalize vertex pos 
RSQ NV.w, NV.w; 
MUL NV, V, NV.w; 


# Each flat edge of the star defines a half-space. The interior 
# of the star is any point within at least 4 out of 5 of them. 

# Start with -3 so that it takes adding 4 ins to equal 1. 

MOV myInOut, -3.0; 


# We need to perform 5 dot products, one for each edge of 
# the star. Perform first 4 in vector, 5th in a second 
# vector along with the blue stripe. 

DP3 distance.x, NV, myHalfSpaced; 

DP3 distance.y, NV, myHalfSpace1; 

DP3 distance.z, NV, myHalfSpace2; 

DP3 distance.w, NV, myHalfSpace3; 


# The half-space planes all intersect the origin. We must 
# offset them in order to give the star some size. 
ADD distance, distance, misc.y; 


CMP distance, distance, 0.0, 1.0; 
DP4 distance, distance, 1.0; 
ADD myInOut, myInOut, distance; 


# set up last star edge and blue stripe 
DP3 distance.x, NV, myHalfSpace4; 

ADD distance.x, distance.x, misc.y; 

ABS distance.y, NV.z; 

SUB distance.y, distance.y, misc.x; 

CMP distance, distance, 0.0, 1.0; 
ADD_SAT myInOut, myInOut, distance.x; 
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LISTING 23.28 Continued 


# red star on yellow background 
LRP surfColor, myInOut, myRed, myYellow; 


# blue stripe down middle 
LRP surfColor, distance.y, surfColor, myBlue; 


DP3 NN.w, N, N; # normalize normal 
RSQ NN.w, NN.w; 
MUL NN, N, NN.w; 


DP3 NL.w, L, L; # normalize light vec 
RSQ NL.w, NL.w; 
MUL NL, L, NL.w; 


ADD NH, NL, {@, @, 1}; # half-angle vector 
DP3 NH.w, NH, NH; # normalize it 

RSQ NH.w, NH.w; 

MUL NH, NH, NH.w; 


# diffuse lighting 

DP3 NdotL, NN, NL; Nek 

MAX NdotL, NdotL, 0.0; # max(N . L, Q) 

ADD NdotL, NdotL, misc.y; # 20% ambient 

MUL surfColor, surfColor, NdotL; # factor in diffuse color 


# specular lighting 


DP3 NdotH, NN, NH; #N.H 

MAX NdotH, NdotH, 0.0; # max(N . H, 0) 

POW specular, NdotH.x, misc.z; # NdotH*60 

MAD oPrC, misc.w, specular, surfColor; # 50% specular intensity 


END 


The half spaces cut through the center of the sphere. This is what we wanted for the beach 
ball, but for the star we need them offset from the center slightly. This is why we add an 
extra constant distance to the result of the half space dot products. The larger you make 
this constant, the larger your star will be. 


Again, we use smoothstep in the GLSL shader and CMP in the low-level shader when 

picking between inside and outside. For efficiency, we put the inside/outside results of the 
first four half spaces into a four-component vector. This way, we can sum the four compo- 
nents with a single four-component dot product against the vector {1,1,1,1}. The fifth half 


Summary 


space’s inside/outside value goes into a lonely float and is added to the other four sepa- 
rately because no five-component vector type is available. You could create such a type 
yourself out of a structure, but you would likely sacrifice performance on most implemen- 
tations, which natively favor four-component vectors. 


If you want to toy with this shader, try this exercise: Convert the star into a six-pointed 
star by adding another half space and adjusting the existing half space planes. Prove to 
yourself how many half spaces your fragments must fall within now to fall within the star, 
and adjust the myInOut counter’s initial value accordingly. 


Summary 


The possible applications of vertex and fragment shaders are limited only by your imagi- 
nation. We’ve introduced a few just to spark your creativity and to provide you with some 
basic building blocks so you can easily jump right in and start creating your own shaders. 
Feel free to take these shaders, hack and slash them beyond recognition, and invent and 
discover better ways of doing things while you're at it. Don’t forget the main objective of 
this book: Make pretty pictures. So get to it! 
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APPENDIX A 
Further Reading 


Dicckame 3D graphics and OpenGL are popular topics, and there are more information 
and techniques in practice than can ever be published in a single book. You might find 
the following resources helpful as you further your knowledge and experience. 


Other Good OpenGL Books 


OpenGL Programming Guide, 4th Edition: The Official Guide to Learning OpenGL, Version 1.4. 
OpenGL Architecture Review Board, Dave Shreiner, Mason Woo, Jackie Neider, and Tom 
Davis. Addison-Wesley, 2003. 


OpenGL Programming for the X Window System. Mark J. Kilgard. Addison-Wesley, 1996. 


Interactive Computer Graphics: A Top-Down Approach with OpenGL, 3rd Edition. Edward 
Angel. Addison-Wesley, 2002. 


The OpenGL Extensions Guide. Eric Lengyel. Charles River Media, 2003. 
OpenGL Shading Language. Randi J. Rost. Addison-Wesley, 2004. 


3D Graphics Books 
3D Computer Graphics. Alan Watt. Addison-Wesley, 1993. 


3D Math Primer for Graphics and Game Development. Fletcher Dunn and Ian Parbery. 
Wordware Publishing, 2002. 


Advanced Animation and Rendering Techniques: Theory and Practice. Alan Watt and Mark Watt 
(contributor). Addison-Wesley, 1992. 


Introduction to Computer Graphics. James D. Foley, Andries van Dam, Steven K. Feiner, John 
F. Hughes, and Richard L. Phillips. Addison-Wesley, 1993. 


Open Geometry: OpenGL + Advanced Geometry. Georg Glaeser and Hellmuth Stachel. 
Springer-Verlag, 1999. 


Mathematics for 3D Game Programming & Computer Graphics. Eric Lengyel. Charles River 
Media, 2001. 
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Web Sites 
The OpenGL SuperBible Web Site 


http: //ww.starstonesoftware.com/OpenGL 


The Official OpenGL Web Site 


http 


://ww.opengl.org 


The Khronos Group OpenGL ES Home Page 


http 


://ww.khronos.org/opengles/index. html 


The SGI OpenGL Extension Registry 


http 


://oss.sgi.com/projects/ogl-sample/registry/ 


SGI’s OpenGL Web Site 


http 


://ww.sgi.com/software/opengl/tech_info.html 


ATI’s Developers Home Page 


http 


://www.ati.com/developer/ index.html 


NVidia’s Developers Home Page 


http 


://developer.nvidia.com/page/home 


3Dlabs’ Developers Home Page 


http 


://ww.3dlabs.com/support/developer/index.htm 


Many Great OpenGL Tutorials (Game Heavy) 


http 
http 
http 
http 
http 
http 


://www.gamedev.net/ 

://nehe.gamedev.net/ 
://ww.xmission.com/~nate/tutors.html 
://ww.paulsprojects.net/opengl/projects1.html 
://ww.gametutorials.com/Tutorials/OpenGL/OpenGL_Pg1.htm 
://ww.codecolony.de/opengl.htm 


APPENDIX B 
Glossary 


Aliasing Technically, the loss of signal information in an image reproduced at some 
finite resolution. It is most often characterized by the appearance of sharp jagged edges 
along points, lines, or polygons due to the nature of having a limited number of fixed- 
sized pixels. 


Alpha A fourth color value added to provide a degree of transparency to the color of an 
object. An alpha value of 0.0 means complete transparency; 1.0 denotes no transparency 
(Opaque). 


Ambient light Light in a scene that doesn’t come from any specific point source or 
direction. Ambient light illuminates all surfaces evenly and on all sides. 


Antialiasing A rendering method used to smooth lines and curves and polygon edges. 
This technique averages the color of pixels adjacent to the line. It has the visual effect of 
softening the transition from the pixels on the line and those adjacent to the line, thus 
providing a smoother appearance. 


ARB The Architecture Review Board. The OpenGL ARB meets quarterly and consists of 
3D graphics hardware vendors. The ARB maintains the OpenGL Specification document 
and promotes the OpenGL standard. 


Aspect ratio The ratio of the width of a window to the height of the window. 
Specifically, the width of the window in pixels divided by the height of the window in 
pixels. 


AUX library A window system independent utility library. Limited but useful for quick 
and portable OpenGL demonstration programs. Now largely replaced by the GLUT library. 


Bézier curve A curve whose shape is defined by control points near the curve rather 
than by the precise set of points that define the curve itself. 


Bitplane An array of bits mapped directly to screen pixels. 


Buffer An area of memory used to store image information. This can be color, depth, or 
blending information. The red, green, blue, and alpha buffers are often collectively 
referred to as the color buffers. 


Cartesian A coordinate system based on three directional axes placed at a 90° orienta- 
tion to one another. These coordinates are labeled x, y, and z. 
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Clipping The elimination of a portion of a single primitive or group of primitives. The 
points that would be rendered outside the clipping region or volume are not drawn. The 
clipping volume is generally specified by the projection matrix. Clipped primitives are 

reconstructed such that the edges of the primitive do not lay outside the clipping region. 


Clip coordinates The 2D geometric coordinates that result from the modelview and 
projection transformation. 


Color index mode A color mode in which colors in a scene are selected from a fixed 
number of colors available in a palette. These entries are referenced by an index into the 
palette. This mode is rarely used and even more rarely hardware accelerated. 


Convex A reference to the shape of a polygon. A convex polygon has no indentations, 
and no straight line can be drawn through the polygon that intersects it more than twice 
(once entering, once leaving). 


Culling The elimination of graphics primitives that would not be seen if rendered. 
Backface culling eliminates the front or back face of a primitive so that the face isn’t 
drawn. Frustum culling eliminates whole objects that would fall outside the viewing 
frustum. 


Destination color The stored color at a particular location in the color buffer. This 
terminology is usually used when describing blending operations to distinguish between 
the color already present in the color buffer and the color coming into the color buffer 
(source color). 


Display list A compiled list of OpenGL functions and commands. When called, a 
display list executes faster than a manually called list of single commands. 


Dithering A method used to simulate a wider range of color depth by placing different- 
colored pixels together in patterns that give the illusion of shading between the two 
colors. 


Double buffered A drawing technique used by OpenGL. The image to be displayed is 
assembled in memory and then placed on the screen in a single update operation, rather 
than built primitive by primitive on the screen. Double buffering is a much faster and 
smoother update operation and can produce animations. 


Extruded The process of taking a 2D image or shape and adding a third dimension 
uniformly across the surface. This process can transform 2D fonts into 3D lettering. 


Eye coordinates The coordinate system based on the position of the viewer. The 
viewer's position is placed along the positive z-axis, looking down the negative z-axis. 


Frustum A pyramid-shaped viewing volume that creates a perspective view. (Near objects 
are large; far objects are small.) 


GLUT library The OpenGL utility library. A window system independent utility library 
useful for creating sample programs and simple 3D rendering programs that are indepen- 


Glossary 


dent of the operating system and windowing system. Typically used to provide portability 
between Windows, X-Window, Linux, and so on. 


Immediate mode A graphics rendering mode in which commands and functions have 
an immediate effect on the state of the rendering engine. 


Literal A value, not a variable name. A specific string or numeric constant embedded 
directly in source code. 


Matrix A 2D array of numbers. Matrices can be operated on mathematically and are 
used to perform coordinate transformations. 


Mipmapping A technique that uses multiple levels of detail for a texture. This technique 
selects from among the different sizes of an image available, or possibly combines the two 
nearest sized matches to produce the final fragments used for texturing. 


Modelview matrix The OpenGL matrix that transforms primitives to eye coordinates 
from object coordinates. 


Normal A directional vector that points perpendicularly to a plane or surface. When 
used, normals must be specified for each vertex in a primitive. 


Normalize The reduction of a normal to a unit normal. A unit normal is a vector that 
has a length of exactly 1.0. 


NURBS_ An acronym for non-uniform rational b-spline. This is a method of specifying 
parametric curves and surfaces. 


Open Inventor A C++ class library and toolkit for building interactive 3D applications. 
Open Inventor is built on OpenGL. 


Orthographic A drawing mode in which no perspective or foreshortening takes place. 
Also called parallel projection. The lengths and dimensions of all primitives are undis- 
torted regardless of orientation or distance from the viewer. 


Palette A set of colors available for drawing operations. For 8-bit Windows color modes, 
the palette contains 256 color entries, and all pixels in the scene can be colored from only 
this set. 


Parametric curve A curve whose shape is determined by one (for a curve) or two (for a 
surface) parameters. These parameters are used in separate equations that yield the indi- 
vidual x, y, and z values of the points along the curve. 


Perspective A drawing mode in which objects farther from the viewer appear smaller 
than nearby objects. 


Pixel Condensed from the words picture element. This is the smallest visual division avail- 
able on the computer screen. Pixels are arranged in rows and columns and are individually 
set to the appropriate color to render any given image. 
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Pixmap A two-dimensional array of color values that comprise a color image. Pixmaps 
are so called because each picture element corresponds to a pixel on the screen. 


Polygon A 2D shape drawn with any number of sides (must be at least three sides). 


Primitive A 2D polygonal shape defined by OpenGL. All objects and scenes are 
composed of various combinations of primitives. 


Projection The transformation of lines, points, and polygons from eye coordinates to 
clipping coordinates on the screen. 


Quadrilateral A polygon with exactly four sides. 


Rasterize The process of converting projected primitives and bitmaps into pixel frag- 
ments in the frame buffer. 


Render The conversion of primitives in object coordinates to an image in the frame 
buffer. The rendering pipeline is the process by which OpenGL commands and statements 
become pixels on the screen. 


Scintillation A sparkling or flashing effect produced on objects when a non-mipmapped 
texture map is applied to a polygon that is significantly smaller than the size of the 
texture being applied. 


Source color The color of the incoming fragment, as opposed to the color already 
present in the color buffer (destination color). This terminology is usually used when 
describing how the source and destination colors are combined during a blending opera- 
tion. 


Spline A general term used to describe any curve created by placing control points near 
the curve, which have a pulling effect on the curve’s shape. This is similar to the reaction 
of a piece of flexible material when pressure is applied at various points along its length. 


Stipple A binary bit pattern used to mask out pixel generation in the frame buffer. This 
is similar to a monochrome bitmap, but one-dimensional patterns are used for lines and 
two-dimensional patterns are used for polygons. 


Tessellation The process of breaking down a complex polygon or analytic surface into a 
mesh of convex polygons. This process can also be applied to separate a complex curve 
into a series of less complex lines. 


Texel Similar to pixel (picture element), a texel is a texture element. A texel represents a 
color from a texture that is applied to a pixel fragment in the frame buffer. 


Texture An image pattern of colors applied to the surface of a primitive. 


Texture mapping The process of applying a texture image to a surface. The surface does 
not have to be planar (flat). Texture mapping is often used to wrap an image around a 
curved object or to produce patterned surfaces such as wood or marble. 


Glossary 1111 


Transformation The manipulation of a coordinate system. This can include rotation, 
translation, scaling (both uniform and nonuniform), and perspective division. 


Translucence A degree of transparency of an object. In OpenGL, this is represented by 
an alpha value ranging from 1.0 (opaque) to 0.0 (transparent). 


Vertex A single point in space. Except when used for point and line primitives, it also 
defines the point at which two edges of a polygon meet. 


Viewing volume The area in 3D space that can be viewed in the window. Objects and 
points outside the viewing volume are clipped (cannot be seen). 


Viewport The area within a window that is used to display an OpenGL image. Usually, 
this encompasses the entire client area. Stretched viewports can produce enlarged or 
shrunken output within the physical window. 


Wireframe The representation of a solid object by a mesh of lines rather than solid 
shaded polygons. Wireframe models are usually rendered faster and can be used to view 
both the front and back of an object at the same time. 
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APPENDIX C 
OpenGL ES 


Openct for Embedded Systems (OpenGL ES) is a lightweight version of OpenGL 
intended to bring portable and standard 3D graphics programming to a wide range of 
embedded systems. The term embedded system refers to a computer embedded in some 
device. Unlike a typical PC, where the computer's primary task is, well, computing, an 
embedded system is a computer that facilitates only the operation of the device it is 
embedded in. Examples of these types of devices are PDAs, cell phones with sophisticated 
graphics displays, medical and diagnostic devices, and automotive and avionic (airplane) 
displays. OpenGL ES is maintained by the Khronos Group, a consortium of media-centric 
companies, which is similar in some respects to the OpenGL Architecture Review Board 
(ARB). In fact, many of the member companies belong to both the ARB and the Khronos 
Group. 


Basically, OpenGL ES is defined as a subset of OpenGL version 1.3, with a few additional 
extensions. This subset is further divided into two more “profiles”: the Common profile 
and the Common-Lite or Safety Critical profile. The Common profile is simply a subset of 
OpenGL functionality intended to make OpenGL smaller in terms of the number of 
commands and in the memory footprint required for implementation. Another goal is to 
eliminate functionality that does not make as much sense in the embedded space. The 
Common-Lite profile is a further reduction of the feature set intended for devices with 
even less memory or available resources. Also called the Safety Critical profile, it is also 
useful in cases in which safety certifications are made easier by a smaller API footprint and 
less code that must be rigorously tested. 


Reduction of Data Types 


OpenGL supports a wide range of data types, and many functions allow you to specify 
data in whatever data type is convenient. The first step in reducing OpenGL is to reduce 
the number of data types supported at the high end and allow some of the smaller data 
types to be used for operations where they were not used before. 


The first data type to go is GLdouble. The loss of this data type eliminates any function 
variations in OpenGL that supported double data types. Functions that are not eliminated 
altogether (see the following section) but use only doubles (gl0rtho, for example) are kept, 
but they are changed to accept floating-point or fixed-point parameters. 
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To make OpenGL smaller for embedded systems, a new data type was added. The GLFixed 
data type is a fixed-point decimal number, and GLclampx is the “clamped” version of 
GLfixed. This type was added because the Common-Lite profile also eliminates GLfloat. 
Floating-point math hardware is often not included on embedded systems, and removing 
the data type removes the memory and performance overhead of having to emulate float- 
ing-point math operations. 


The GLbyte, GLubyte, and GLshort function suffixes were also eliminated. This leaves only 
the command suffixes i, f, and x, with f also being eliminated from the Common-Lite 
profile function suffixes. You still can specify vertex and color data components as short 
or byte data types (but only in vertex arrays). The only exception is that color values may 
be specified as ubyte, but not as short. By using these smaller data types, you can reduce 
program size and data storage as well. 


Totally Gone 


The OpenGL ES specification (included on the CD) is more about what is removed from 
OpenGL than what OpenGL ES contains. This means it is not possible to understand 
OpenGL ES operation outside an understanding of OpenGL. Essentially, for both the 
Common and Common-Lite implementations, the following pieces of functionality have 
been removed in their entirety: 


¢ Use of Begin/End for geometry specification (OpenGL ES uses only vertex arrays.) 
¢ Interleaved arrays or support for glArrayElement 

¢ Display lists 

¢ Evaluators 


¢ Color index mode 


User-defined clipping planes 


Line or polygon stippling 
e glRect 

¢ Imaging subset 

e Feedback 

¢ Selection 

e Accumulation buffer 

e Edge flags 

© glPolygonMode 


Greatly Reduced Functionality 


* The primitives GL_QUADS, GL_QUAD_STRIP, and GL_POLYGON 


¢ Attribute saving: glPushAttrib, glPopAttrib, glPushClientAttrib, or 
glPopClientAttrib 


Greatly Reduced Functionality 


Many other features of OpenGL ES are greatly reduced in their scope and functionality. 
OpenGL ES still provides limited support for specifying the current color, normal, and 
texture coordinates using fixed-point or floating-point forms of the commands glColor4, 
glNormal3, and MultiTexCoord4. You use these functions, for example, when one of these 
states remains constant for an entire vertex array. 


The full transformation pipeline is still mostly in place, but it works only with the newly 
specified subset data types (no doubles and so forth). OpenGL ES also does not support the 
transpose matrix, and the minimum depth of the modelview matrix stack has been 
changed from 32 to 16. 


Texture Mapping 

Only 2D textures are supported in OpenGL ES. Multitexture remains optional, but the 
GL_COMBINE texture environment is not. There is no support for texture coordinate genera- 
tion or cube maps. There is no support for texture borders or the wrap modes GL_CLAMP or 
GL_CLAMP_TO_BORDER. Also missing are texture proxies, the LOD clamping, and bias para- 
meters. Finally, texture compression is supported, but you cannot read back a compressed 
texture, and you cannot use glTexImage2D to compress an uncompressed image. 


Raster Operations 

Most raster functionality is gone from OpenGL ES. The g1PixelStore function is still 
partially supported, but only for packing and unpacking texture data. You can still read 
pixels with glReadPixels, but gl1DrawPixels, glPixelTransfer, and glPixelZoom are not 
supported. Although glReadPixels still exists, you cannot use it to read from the depth or 
stencil buffers. The glReadBuffer, gl1DrawBuffer, and glCopyPixels functions were also 
dropped. Polygon offset is supported only in fill mode (g1PolygonMode is no longer 
supported anyway). 


Lighting 

OpenGL ES must still support at least eight light sources, and two-sided lighting is still 
supported, although both sides must now have the same material properties (no difference 
between front and back material properties any longer). The only color material mode is 
GL_AMBIENT_AND_DIFFUSE, and the secondary color and local viewer lighting models were 
dropped. 


1115 


1116 


APPENDIX C_ OpenGL ES 


Conclusion 


OpenGL ES is a lean-and-mean 3D API providing the bare minimum, but sufficient, 
features to meet the needs of 3D graphics programmers in the widely defined embedded 
systems marketplace. Programming for OpenGL ES requires an SDK for the target platform 
that contains information on how to create and use a 3D context for that device’s screen. 
PC emulators for OpenGL ES are just becoming available at the time of this printing, and 
you can check the Khronos (ww.khronos.org) Web site for a list of vendors supporting 
OpenGL and links to further developers’ resources. 


Index 


Symbols 


2D convolution filters, 345, 356-357 
2D imaging, 12, 301 

2D Bézier curves 
control points, 494 
DrawPoints function, 494 
glEvalCoord1f function, 495 
RenderScene function, 494-495 
sample code listing, 491-494 

2D Cartesian coordinates, 26 

2D fonts, 682-684, 739 

bitmaps, 301-302 
campfire bitmap example, 303-307 
defined, 302 
drawing, 308, 353 
pixelmaps, 302 
raster position, 307-308, 370-371, 374 

imaging subset, 335-337 
color lookup tables, 341-344, 354-359, 363 
color matrix, 340-341 
convolutions, 344-348, 356-357, 362-363 
histograms, 349-352, 364-367 
IMAGING sample program, 336-339 

pixels 
campfire image example, 312-316 
copying, 317, 360-361 
data types, 311 
luminance, 310 
mapping, 333-334, 368 
moving, 316-317 
OPERATIONS sample program, 320-327 
pixel formats, 310-312 
pixel packing, 309-310, 368-369 
pixel transfer, 329-333, 369-370 
pixel zoom, 327-328, 370 
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pixmaps, 310-311, 361 

reading, 316, 371-372 

saving, 317-318, 320 
textures 

OpenGL ES, 1115 

texture example, 383-390 


3D graphics. See also colors; primitives; 
rendering 


3D canvases, 90-91 
3D fonts, 679-681 
3D text rendering, 681 
animation, 62 
animated bouncing square, 63-66 
double-buffering, 66-67 
glutTimerFunc function, 63, 87-88 
antialiasing, 280, 936 
defined, 20 
enabling, 280 
jaggies, 280 
multisampling, 283-285 
switching between antialiasing and 
normal rendering, 282-283 
Bézier curves, 487-488 
2D curves, 491-495 
3D curves, 496-499 
breakpoints, 490 
continuity, 490 
control points, 489-490 
cubic curves, 490 
degree, 490 
evaluating, 496 
evaluators, 491, 521-523 
lighting, 500 
mapping grids, 496, 523-524 
normals, 500 
order, 490 
parametric representation, 488-489 
piecewise curves, 490 
quadratic curves, 490 
blending, 19, 1043-1048 
bolt model 
breaking into parts, 548-549 
head, 549-554 


model assembly, 561-562 
shaft, 554-557 
threads, 557-561 

clipping volumes, 58-62 

coordinate systems, 25-26 
2D Cartesian coordinates, 26 
3D Cartesian coordinates, 29 
coordinate clipping, 27 
planes, 26 
vertices, 29 
viewports, 27-29 

cubes, 169 

defined, 12-13 

display lists, 563 
batch processing, 563-564 
converting to, 566-567 
creating, 565, 602-603, 607-608 
deleting, 565, 599 
display list caveats, 566 
executing, 566, 597 
executing array of, 566, 597-598 
preprocessed batches, 564-566 


ranges of empty display lists, generating, 
565, 603-604 


testing existance of, 605 
fog, 19, 286-289 
example, 286 


fog coordinate generating vertex shaders, 
1032-1037 


glFog function, 287-289, 298-299 
GL_EXP equation, 288 
GL_EXP2 equation, 288 
GL_LINEAR equation, 288 
turning on/off, 287 
foreshortening, 15 
hidden surface removal, 16 
history of, 11 
image processing, 1061-1062 
blur, 1062-1065 
dilation, 1067-1069 
edge detection, 1070-1072 
erosion, 1067-1069 
sharpen, 1065-1067 


interactive graphics, 611 
feedback buffers, 625, 634-635 
feedback data, 625-626 
feedback example, 627-634 
passthrough markers, 627, 636 
picking, 617-624 
primitives, naming, 612-614 
selection buffers, 615-617, 638 
selection mode, 614-615 
lighting, 17, 224-225, 229, 1072-1073 
adding to materials, 227-228 
ambient light, 225, 228, 232-233 
Bézier curves, 500 


diffuse lighting, 225, 228-229, 1018-1021, 


1073-1077 
enabling, 229 
fixed vertex processing, 932, 934 
light intensity and distribution, 226-227 
light particles, 212-213 
light sources, 234-235, 240-241, 250-251, 
268-270 
lighting models, 229-230, 271-272 
OpenGL ES, 1115 
specular lighting, 226-229, 244-248 


specular lighting fragment shaders, 
1077-1083 


specular lighting vertex shaders, 
1021-1024 


spotlights, 251-256 

wavelengths, 212 
materials 

lighting, 227-229, 232-233 

properties, 227, 230-233, 241-242, 272 
non-real-time applications, 23-24 
NURBS, 501-502 

callbacks, 531-532 

creating, 503, 530 

deleting, 503, 526 

error codes, 533 

knots, 502 

NURBS curves, 508, 534 

piecewise trimming curves, 538-539 
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properties, 504, 529, 534-536 
sampling and culling matrices, 530 
surface definition, 504-505, 536-537 
trimming, 505-508, 525, 529 
performance, measuring, 567-572 
SPHEREWORLD example, 569-572 
stopwatch, 568 
perspective, 13-16 
points, 1037-1039 
projections, 30-31, 160 
quadric surfaces, 478 
callbacks, 539 
cylinders, 481, 525-526 
disks, 483, 527-528 
draw styles, 479, 539-540 
drawing, 480, 483 
modeling with, 483-486 
normals, 480, 540 
orientation, 480, 540-541 
quadric states, 478-480 
snowman model example, 483-486 
spheres, 480-481, 541-542 
texture coordinates, 480, 541 
real-time applications, 12, 21-24 
shading, 16 
shadows, 17, 258, 907-908 
alpha test function, 928 
ambient lighting, 913-914 
defined, 258-259 
depth textures, 913, 919 
diffuse lighting, 914 
drawing, 913-914 


eye linear texture coordinate generation, 
917 


GL_ARB_shadow_ambient extension, 
925-926 


hidden surface removal, 918 

light viewpoint, drawing, 908 

light viewpoint, rendering, 909-913 
percentage-closer filtering, 919 
polygon offset, 926, 930 

rendering, 262-264 


How can we make this index more useful? Email us at indexes@samspublishing.com 
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sample code listing, 920-925 

scenes, fitting to window, 909 

shadow comparison, 918-920 

shadow maps, 911, 915-918 

shadow projection matrix, 261-262 
shadow transformation matrix, 259-260 
texture coordinates, 918 


tessellation, 508-510 


callbacks, 510-512, 543-544 
convex polygons, 515-518 
creating, 531 

deleting, 527 

properties, 545 

sample program, 512-514 
vertex data, 512, 546 


textures, 375, 435 


active texture, 467-468 

allocating, 405 

anisotropic filtering, 403, 438-440 
applying, 935 

beach ball texture, 1091-1096 

binding, 405, 417 

checkerboard texture, 1084-1090 
compressed textures, 440-443, 468-471 
copying from color buffer, 379, 417-418 
cube mapping, 453-457 

deleting, 405, 419-420 

dependent texture lookups, 1058 

eye linear mapping, 452 

filtering, 392-393 

internal formats, 377 

loading, 376-379, 427-429 
mipmapping, 400-405, 431-433 
multitexture, 406-415, 457-465, 471-473 
names, generating, 420 

object linear mapping, 450-451 
OpenGL ES, 1115 

parameters, 392, 420-422, 429-430 
pixel data types, 378 

priorities, 416, 424 

procedural texture mapping, 1083-1084 
quadric surfaces, 480, 541 


resident textures, 415-417 
returning, 423 

secondary color, 435-437, 473-474 
simple 2D example, 383-390 
sphere mapping, 452-453 

texel formats, 18, 377-378 

texture combiners, 465-467 


texture coordinates, 380-382, 424-426, 
443-450, 474-475, 934 


texture environment mode, 390-392, 
426-427 


texture matrix, 382 

texture objects, 405-406 

texture states, 376 

texture wrap, 394-395 
toon-shading, 395-400 

toy ball texture, 1096, 1099-1103 
updating, 379-380, 418-419 
verifying, 423-424 


torus, 189 
transformations 


actor frames, 194-195 

adding together, 192-193 

ATOM program example, 175-178 
camera management, 196 
column-major matrix ordering, 186-188 
creating and loading, 189-192 

Euler angles, 195 

eye coordinates, 161 


hardware T&L (transform and lighting), 
188 


identity matrix, 172-174 

matrix loading, 188-189, 205 
matrix math, 159-160, 166-167 
matrix multiplication, 192, 206 
matrix stacks, 174-175 

modeling transformations, 161-162 
modelview matrix, 168-171 
modelview transformations, 161-165 
projections, 161, 165-166, 178-183 
rotation, 170, 208 

row-major matrix ordering, 187 
scaling, 171, 208 


SPHEREWORLD sample program, 196-203 


squash-and-stretch vertex shaders, 
1040-1043 


TRANSFORM sample program, 189-192 
transformation pipline, 167-168 
translation, 169, 209 
viewing transformations, 161-162 
viewport transformations, 161, 166 
transparency, 19 
vertex arrays, 574 
data types, 580 
enabling, 579 
geometry, loading, 578-579 
indexed vertex arrays, 582-596 
pointers, 580-581, 610 
rendering, 581-582 
sizes, 580 
STARFIELD sample program, 575-578 
viewports, 58-59 
3-3-2 palettes, 674-675 
4-bit color mode, 217 
8-bit color mode, 217 
16-bit color mode, 218 
24-bit color mode, 218 
32-bit color mode, 218 


A 


ABS instruction, 950 
accelerated OpenGL implementations, 42 
accumulation buffer, 289-292 
accumulation operations, 289-290 
clearing, 297-298 
glAccum function, 289-290, 295 
motion blur, 290-292 
accumulation operations, 289-290 
active texture, setting, 467-468 
actor frames, 193-195 
ADD instruction, 950 
addresses, 954, 961 
AGL/Carbon APIs, 744 
bitmap fonts, 760-775 
context management, 747 


alpha testing 1121 


double-buffered rendering, 747 

pixel formats, 745-746 

spinning cube sample program 

bitmap fonts, 760-775 
initial code listing, 747-760 

AGL_ACCELERATED constant, 745 
AGL_ACCUM_ALPHA_ SIZE constant, 745 
AGL_ACCUM_BLUE SIZE constant, 745 
AGL_ACCUM_GREEN SIZE constant, 745 
AGL_ACCUM_RED SIZE constant, 745 
AGL_ALPHA_SIZE constant, 745 
AGL_AUX_BUFFERS constant, 745 
AGL_BACKING_STORE constant, 745 
AGL_BLUE_SIZE constant, 745 
AGL_BUFFER_SIZE constant, 745 
AGL_CLOSEST_POLICY constant, 745 
AGL_DEPTH_SIZE constant, 745 
AGL_DOUBLEBUFFER constant, 745 
AGL_FULLSCREEN constant, 745 
AGL_GREEN_SIZE constant, 745 
AGL_LEVEL constant, 745 
AGL_MINIMUM_POLICY constant, 746 
AGL_NONE constant, 746 
AGL_OFFSCREEN constant, 746 
AGL_PIXEL_SIZE constant, 746 
AGL_RED_SIZE constant, 746 
AGL_RGBA constant, 746 
AGL_STENCIL_SIZE constant, 746 
AGL_STEREO constant, 746 
aglChoosePixelFormat function, 775, 788 
aglCreateContext function, 747, 788 
ag|DestroyContext function, 747, 789 
aglSetCurrentContext function, 747, 789 
aglSetDrawable function, 747, 790 
aglSwapBuffers function, 747, 790 
aglUseFont function, 760, 790-791 
aliases, 20, 954, 960 
allocating 

selection buffers, 616, 638 

texture objects, 405 
alpha testing, 293-294, 928 
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ambient light, 225 
calculating effects of, 228 
sample code listing, 232-233 
shadows, 913-914 
ambientLight[] array, 240 
angles, Euler, 195 
animation, 62 
animated bouncing square, 63-66 
double-buffering, 66-67 
glutTimerFunc function, 63, 87-88 
anisotropic filtering, 403, 438-440 
antialiasing, 100, 280, 936 
defined, 20 
enabling, 280 
jaggies, 280 
multisampling, 283-285 
switching between antialiasing and normal 
rendering, 282-283 
APIs (application programming interfaces), 44 
AGL/Carbon, 744 
bitmap fonts, 760-775 
context management, 747 
double-buffered rendering, 747 
pixel formats, 745-746 
spinning cube sample program, 747-760 
API wars, 37 
ApplicationServices, 744 
Cocoa, 744 
NSOpenGL class, 775-778 
spinning cube sample program, 778-787 
GLUT, 744 
applications. See programs 
ApplicationServices, 744 
ARB (Architecture Review Board), 34-35 
ARB_ extension prefix, 73 
arbitration (palettes), 670-672 
Architecture Review Board (ARB), 34-35 
ARL instruction, 952 
arrays, 989-990 
ambientLight[], 240 
array access, 992 
array indices, 881 
diffuseLight[], 240 


lightPos[], 240, 250 
parameter arrays, 956-957 
specref[], 246 
vertex arrays, 574, 867 
data types, 580 
enabling, 579, 869 
geometry, loading, 578-579 
indexed vertex arrays, 582, 585, 588-596 
pointers, 580-581, 610 
rendering, 581-582 
sizes, 580 
spherical particle clouds, 867-872 
STARFIELD sample program, 575-578 
asynchronous operations, 564 
ATL_ extension prefix, 73 
ATOM program 
glPopMatrix function, 178 
glPushMatrix function, 178 
glRotatef function, 178 
giTranslatef function, 178 
RenderScene function, 175-177 
attaching program objects, 984, 999 
attributes, 954, 957 
attribute groups, 80 
attribute qualifier, 990 
attribute stack, 69, 80 
fragment attributes, 958-959 
vertex attributes, 957-958 
autoconf 
configure.in file, 794-795 
Makefile.in file, 795 
averaging normals, 248-249 


B-splines. See NURBS (non-uniform rational 
B-splines) 
backface culling, 118-121, 144 
batch processing, 563-564 
flushing, 564 
preprocessed batches, 564-566 


beach ball texture, 1091-1096 


high-level fragment shader, 1092-1094 
low-level fragment shader, 1094-1096 


BeginPaint function, 668 
BEZ3D program, 496-499 
Bézier curves, 487-488 
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BITMAPS program, 303-307 
blending colors, 19, 275-276 


antialiasing, 936 
enabling, 280 
jaggies, 280 
multisampling, 283-285 


2D curves 
control points, 494 
DrawPoints function, 494 
glEvalCoord1f function, 495 
RenderScene function, 494-495 
sample code listing, 491-494 

3D curves, 496-499 

BEZIER program, 491-494 

breakpoints, 490 

continuity, 490 

control points, 489-490 

cubic curves, 490 

degree, 490 

evaluating, 496 

evaluators, 491, 521-523 

lighting, 500 

mapping grids, 496, 523-524 

normals, 500 

order, 490 

parametric representation, 488-489 

piecewise curves, 490 

quadratic curves, 490 


BEZIER program, 491-494 
binding 


Buffer objects, 874, 882 
low-level shaders, 946, 967 
texture objects, 405, 417 


bitmaps, 301-302 


bitmap fonts 
APL/Carbon APIs, 760-775 
GLX, 812-824 
BITMAPS program, 303-307 
campfire bitmap example, 303-307 
defined, 302 
drawing, 308, 353 
pixelmaps, 302 


raster position, 307-308, 370-371, 374 


switching between antialiasing and 
normal rendering, 282-283 
blending equations 
changing, 279-280, 296 
default blending equation, 276 
GL_FUNC_ADD, 280 
GL_FUNC_REVERSE_SUBTRACT, 280 
GL_FUNC_SUBTRACT, 280 
GL_MAX, 280 
GL_MIN, 280 
blending factors, 276-277 
destination colors, 276 
enabling blending, 276 
glBlendColor function, 295-296 
glBlendEquation function, 279, 296 
glBlendFunc function, 276-277, 296-297 
glBlendFuncSeparate function, 280, 297 
REFLECTION sample program, 278-279 
source colors, 276 


vertex blending shaders, 1043-1044, 1046, 
1048 


blur, 1062-1065 
bolt model 
breaking into parts, 548-549 
head, 549-554 
model assembly, 561-562 
shaft, 554-557 
threads, 557-561 
bool data type, 988 
bouncing square animation, 63-66 
bounding boxes, 895-899 
breakpoints of curves, 490 
buffers, 132, 865-866 
accumulation buffer, 289-290, 292 
accumulation operations, 289-290 
clearing, 297-298 
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glAccum function, 289-290, 295 
motion blur, 290-292 
array indices, 881 
binding to, 874, 882 
buffer targets, 132-134 
checking existence of, 881, 888 
color buffers 
clearing color, 53-54, 75 


copying convolution filters from, 346, 
359-360 


copying textures from, 379, 417-418 
glClear function, 54 
copying data into, 873-874, 881-882 
creating, 874 
deleting, 874, 885 
depth buffers, 134-135 
double-buffering, 66-67 
feedback buffers 
loading and parsing, 632-634 
setting, 625, 634-635 
types, 625 
frame buffers, 43, 929 
initializing, 874 
listing available buffer names, 874, 885 
mapping 
glMapBuffer function, 876-881, 888 
object access modes, 877 
sample code listing, 878-881 
migrating to, 872-873 
multisample buffers, 285 
Pbuffers, 832-839, 855 
pixel rendering buffer, 653 
querying buffer object data store, 881, 887 
querying pointer to, 881, 886 
querying state of, 881, 885 
rendering with, 874 
selection buffers, 615-617, 638 
state queries, 881 
stencil buffers 
glClearStencil function, 143 


glStencilFunc function, 136-138, 154-155 


glStencilMask function, 140, 155 


glStencilOp function, 138-140, 155-156 


unmapping, 878, 889 
usage hints, 876 
vertex arrays 
enabling, 867 
sphere vertex array, 869, 871-872 
spherical particle clouds, 867-868 
built-in variables, 990-991 
bvec2 data type, 988 
bvec3 data type, 988 
bvec4 data type, 988 


¢ 


C language, 44-46 
C++ language, 44 
calculations 
blending equations 
changing, 279-280, 296 
default blending equations, 276 
GL_FUNC_ADD, 280 
GL_FUNC_REVERSE_SUBTRACT, 280 
GL_FUNC_SUBTRACT, 280 
GL_MAX, 280 
GL_MIN, 280 
fog equations, 288 
callbacks, 52, 82-83 
NURBS, 531-532 
OpenGL widgets, 841-842 
quadric surfaces, 539 
tessellator callbacks, 510-512, 543-544 
camera management, 196 
campfire bitmap, 303-307 
campfire image 
gltLoadTGA function, 314-316 
RenderScene function, 312-313 
canvases, 90-91 
CARBON sample program, 747-775 
Carbon/AGL APIs, 744 
bitmap fonts, 760-775 
context management, 747 


double-buffered rendering, 747 
pixel formats, 745-746 
spinning cube sample program 
bitmap fonts, 760-775 
initial code listing, 747-760 
CARBONFONTS sample program, 760-775 
cards 
CGA (Color Graphics Adapter), 215 
EGA (Enhanced Graphics Adapter), 216 
Hercules, 215 
Super-VGA, 216 
VGA (Video Graphics Array), 216 
Carmack, John, 37 
Cartesian coordinates, 26, 29 
cartoons with texture (toon-shading), 395-400 
cathode ray tubes (CRTs), 12 
CCUBE program 
drawing colors, setting, 220-221 
shading 
flat shading, 223 
glColor function, 221-223 
shading models, selecting, 223, 274 
smooth shading, 221-223 
cell-shading, 395-400 
CGA (Color Graphics Adapter) cards, 215 
chains of lookups, 964 
ChangeDisplaySettings function, 689 
ChangeSize function, 57-58, 90, 240, 303 
checkerboard texture, 1084-1090 
high-level fragment shader, 1087-1088 
low-level fragment shader, 1088-1090 
ChoosePixelFormat function, 656-657, 725-726 
classes, NSOpenGL, 775-778 
clearing accumulation buffer, 297-298 
clearing color, setting, 53-54, 75 
clipping, 934-935 
clipping regions, 27 
clipping volumes, 58-62, 79-80 
clockwise winding, 110 
CMP instruction, 953 
Cocoa API, 744 
NSOpenGL class, 775-778 
spinning cube sample program, 778-787 
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COCOACUBE sample program, 779-787 
color buffers 
clearing 
clearing color, 53-54, 75 
glClear function, 54 


copying convolution filters from, 346, 
359-360 


color cube program 
drawing colors, setting, 220-221 
shading 
flat shading, 223 
glColor function, 221-223 
shading models, selecting, 223, 274 
smooth shading, 221-223 
Color Graphics Adapter (CGA) cards, 215 
color logical operations, 292-293, 299 
color lookup tables, 341-344 
copying, 343, 358-359 
parameters, 343, 355-356, 363 
proxies, 343 
replacing, 344, 354, 358 
setting up, 341, 354-355 
colors, 16 
accumulation buffer, 289-292 
accumulation operations, 289-290 
clearing, 297-298 
glAccum function, 289-290, 295 
motion blur, 290-292 
alpha testing, 293-294 
blending, 275-276 
antialiasing, 280-285, 936 
blending equations, 276, 279-280, 296 
blending factors, 276-277 
destination colors, 276 
enabling, 276 
glBlendColor function, 295-296 
glBlendEquation function, 279, 296 
glBlendFunc function, 276-277, 296-297 
glBlendFuncSeparate function, 280, 297 
REFLECTION sample program, 278-279 
source colors, 276 
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CGA (Color Graphics Adapter) cards, 215 
clearing color, 53-54, 75 
color buffers 

clearing color, 53-54, 75 


copying convolution filters from, 346, 
359-360 


color conversion 
color inversion, 1055-1056 
grayscale, 1052-1053 
heat signature, 1056-1058 
sepia tone, 1053-1055 

color depth, 217-218 

color logical operations, 292-293, 299 

color lookup tables, 341-344 
copying, 343, 358-359 
parameters, 343, 355-356, 363 
proxies, 343 
replacing, 344, 354, 358 
setting up, 341, 354-355 

color matrix, 340-341 

color sum, 935 

color theory 
human eye structure, 214 
light particles, 212-213 
wavelengths, 212 

color tracking, 231 

dithering, 294 

drawing colors, 220-221, 266 

EGA (Enhanced Graphics Adapter) cards, 216 

Hercules card, 215 

lighting conditions, 224-225 
ambient light, 225 
diffuse light, 225 
light intensity and distribution, 226-227 
specular light, 226 

masking, 292, 298 

matching, 669-670 

monitors, 214-215 

palettes, 217 

polygons, 116 

RGB colorspace, 218-220 

screen resolution, 217 

secondary color, 435-437, 473-474 

sending to frame buffer, 929 


shading 
flat shading, 223 
glColor function, 221-223 
shading models, selecting, 223, 274 
smooth shading, 221-223 
Super-VGA cards, 216 
VGA (Video Graphics Array) cards, 216 
Windows palettes 
3-3-2 palettes, 674-675 
color index mode, 679 
color matching, 669-670 
creating, 670-678 
destroying, 677-678 
determining need for, 673 
LOGPALETTE structure, 673-674 
message handlers, 671-672 
palette arbitration, 670-672 
PALETTEENTRY structure, 674 
restrictions, 678-679 
column-major matrix ordering, 186-188 
combiners (texture), 465-467 
command queue, flushing, 54-55, 77 
commands 
make, 796 
xdpyinfo, 797 
common instruction set, 950-951 
compiling low-level shaders, 946-947, 977 
compiling high-level shaders, 983-984, 1000 
component selectors, 994 
compressed textures, 440-441 
compressed texture formats, 441-442 
loading, 442-443, 468-469, 471 
parameters, 441-442 
cone cells, 214 
configure.in file, 794-795 
conformance, 35 
const qualifier, 990 
constants. See names of specific constants 
constructors, 992-994 
context management 
AGL/Carbon APIs, 747 
GLX, 800 
Pbuffers, 833 


continuity of curves, 490 
control flow 
discard statement, 996 
functions, 996-999 
if/else statements, 995-996 
loops, 995 
control points, 489-490 
converting 
colors 
color inversion, 1055-1056 
grayscale, 1052-1053 
sepia tone, 1053, 1055 
display lists, 566-567 
convex polygons, 128 
drawing, 515-516 
multiple contours, 516-518 
convolutions, 344-346 


combining with other imaging operations, 
345-346 


copying from color buffer, 346, 359-360 
glConvolutionFilter1D function, 347-348, 356 


glConvolutionFilter2D function, 345, 
356-357 


kernels, 344 

one-dimensional convolution filters, 347-348, 
356 

parameters, 348, 362-363 

separable filters, 346-347, 373 


two-dimensional convolution filters, 345, 
356-357 


coordinate systems, 25-26 

2D Cartesian coordinates, 26 

3D Cartesian coordinates, 29 

coordinate clipping, 27 

eye coordinates, 161 

matrices 
column-major matrix ordering, 186-188 
identity matrix, 172-174 
loading, 188-189, 205 
matrix math, 159-160, 166-167 
matrix stacks, 174-175 
modelview matrix, 168-171 
multiplication, 192, 206 
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row-major matrix ordering, 187 
specifying, 206 
planes, 26 


texture coordinates, 380-382, 424-426, 
443-450, 474-475 


vertices, 29 
viewports, 27-29 
copying 
color lookup tables, 343, 358-359 


convolution filters from color buffer, 346, 
359-360 


data to buffer objects, 875-876, 883-884 
pixels, 317, 360-361 
rendering context, 732 
textels into depth texture, 913 
textures from color buffer, 379, 417-418 
cos function, 97 
COS instruction, 953 
counterclockwise winding, 110 
CreatePalette function, 670, 673 
CreateWindow function, 660, 686 
CRTs (cathode ray tubes), 12 
CS_OWNDC constant, 661-663 
cube mapping, 453, 455-457 
CUBEDX program, 582-585 
CUBEMAP program, 455-456 
cubes, 169 
cubic curves, 490 
culling, 118-121, 144 
current rendering context 
returning, 736 
setting, 658, 737 
curves. See also surfaces 
approximating with lines, 102-104 
Bézier curves, 487-488 
2D curves, 491-495 
3D curves, 496-499 
breakpoints, 490 
continuity, 490 
control points, 489-490 
cubic curves, 490 
degree, 490 
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evaluating, 496 
evaluators, 491, 521-523 
lighting, 500 
mapping grids, 496, 523-524 
normals, 500 
order, 490 
parametric representation, 488-489 
piecewise curves, 490 
quadratic curves, 490 
NURBS, 501-502 
callbacks, 531-532 
creating, 503, 530 
deleting, 503, 526 
error codes, 533 
knots, 502 
NURBS curves, 508, 534 
piecewise trimming curves, 538-539 
properties, 504, 529, 534-536 
sampling and culling matrices, 530 
surface definition, 504-505, 536-537 
trimming, 505-508, 525, 529 
cylinders, 481, 525-526 


D 


DAGs (directed acyclic graphs), 25 
data types, 45-46 
GLbyte, 1114 
GLClampx, 1114 
GLdouble, 1113 
GLFixed, 1114 
GLfloat, 1114 
GLshort, 1114 
GLTMatrix, 190 
GLubyte, 1114 
GLUQuadricObj, 479 
OpenGL ES, 1113-1114 
pixel data, 311 
table of, 988 
vertex arrays, 580 
degree of curves, 490 


deleting 


buffer objects, 874, 885 

display lists, 565, 599 

items from attribute stack, 69, 80 
low-level shaders, 948, 968 
NURBS, 503, 526 

occlusion queries, 903-904 
program objects, 984, 1002 
rendering context, 663-667, 732 
shader objects, 982, 1002 
tessellator objects, 527 

texture objects, 405, 419-420 
vertex shaders, 982, 1002 
Windows palettes, 677-678 


dependent lookups, 964, 1058 
depth buffers, 134-135 

depth of color, 217-218 

depth of matrix stack, 175 
depth textures, 913, 919 


DescribePixelFormat function, 654, 673-675, 
726-729 


destination colors, 276 
detaching program objects, 984, 1002 
development of OpenGL, 33-34 


API wars, 37 

ARB (Architectural Review Board), 34-35 
Direct3D, 38 

DirectX, 36 

Fahrenheit, 39 

future technology, 39-40 
gaming, 37-38 

IRIS GL, 34 

licensing and conformance, 35 
Mini-Client Driver (MCD), 38-39 
PC applications, 36-37 


device contexts, 648-650, 661-663 
diffuse lighting, 225, 1073-1077 


calculating effects of, 228-229 

high-level vertex shader, 1018-1019 

interpolant generating high-level fragment 
shader, 1073 

interpolant generating low-level fragment 
shader, 1074-1075 


low-level vertex shader, 1019-1021 
shadows, 914 
diffuseLight[] array, 240 
dilation, 1067-1069 
Direct Rendering Infrastructure (DRI), 796 
Direct3D, 38 
DirectDraw, 36 
directed acyclic graphs (DAGs), 25 
DirectX, 36 
disabling 
fog, 287 
multisampling, 284 
program objects, 986, 1013 
States, 68, 75-76 
discard statement, 996 
disks, drawing, 483, 527-528 
display callback function, 52, 82-83 
DISPLAY environment variable, 798 
display lists, 563 
batch processing, 563-564 
converting to, 566-567 
creating, 565, 602-603, 607-608 
deleting, 565, 599 
display list caveats, 566 
executing, 566, 597 
executing array of, 566, 597-598 
preprocessed batches, 564-566 


ranges of empty display lists, generating, 565, 
603-604 


testing existance of, 605 
display modes 

double-buffer mode, 52 

initializing, 83 

setting, 51 

single-buffer mode, 51 
Display pointer, 798 
displays. See monitors 
distribution of light, 226-227 
dithering, 294 
DLLs (dynamic link libraries). See libraries 
double-buffering 

animation, 66-67 

double-buffered mode, 52 


drawing 


double-buffered rendering, 747 
double-buffered windows, 801 
DP3 instruction, 950 
DP4 instruction, 950 
DPH instruction, 950 
draw styles (quadric surfaces), 479, 539-540 
DrawGeometry function, 290 
DrawGround function, 200-201 
drawing, 89-90. See also rendering 
3D canvases, 90-91 
bitmaps, 308, 353 
buffers 
buffer targets, 132-134 
depth buffers, 134-135 
stencil buffers, 136-140, 143, 154-156 
convex polygons, 128, 515-518 
cubes, 169 
curves, 102-104 
cylinders, 481, 525-526 
disks, 483, 527-528 
drawing colors, setting, 220-221, 266 
edges, 129-131 
general polygons, 123 
lines 
approximating curves with, 102-104 
glBegin/glEnd functions, 100 
line loops, 102 
line stippling, 106-108, 149 
line strips, 102 
line width, 104-106, 150 
sample code listing, 100-102 
nonconvex polygons, 129-131 
pixels, 90 
planar polygons, 128 
points, 93-94 
glBegin function, 93 
glEnd function, 93 
point size, 97-100, 151 
sample code listing, 94-95 
polygon construction rules, 128-129 
quadric surfaces, 483 
quadrilaterals, 122-123 
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rectangles, 57-58, 81 
scissor box, 135-136, 154 
solid objects, 112 
colors, 116 
culling, 118-121, 144 
hidden surface removal, 116-118 
polygon modes, 121, 152 
RenderScene function, 113-116 
SetupRC function, 113-116 
spheres, 480-481, 541-542 
spotlights, 253-256 
stippling, 123-127, 153 
subdivision, 129-131 
triangles 
glBegin/glEnd functions, 109 
sample code listing, 113-116 
triangle fans, 112 
triangle strips, 111 
winding, 110-111 
vertices, 92-93, 156 
Drawjet function, 262 
DrawObjects function, 629 
DrawPoints function, 494 
drawRect function, 777 
DrawTorus function, 189-190 
DrawWorld function, 279 
DRI (Direct Rendering Infrastructure), 796 
drivers, IDC (Installable Client Driver), 644-645 
DST instruction, 950 
dynamic link libraries (DLLs). See libraries 


E 


edge detection, 1070-1072 

edge flags, 129 

edges (polygons), 129-131, 147 

EGA (Enhanced Graphics Adapter) cards, 216 


embedded systems. See OpenGL ES (Open GL 
for Embedded Systems) 


enabling 
antialiasing, 280 
blending, 276 
fog, 287 
lighting, 229 
multisampling, 284 
program objects, 986, 1013 
states, 68, 75-76 
vertex arrays, 579, 869 
EndPaint function, 668 
Enhanced Graphics Adapter (EGA) cards, 216 
entrypoints, 692-693 
enumerating pixel formats, 654-655, 726-727, 
729 


environment variables, DISPLAY, 798 
environments, texture environment mode, 
390-392, 426-427 
equations 
blending equations 
changing, 279-280, 296 
default blending equations, 276 
GL_FUNC_ADD, 280 
GL_FUNC_REVERSE_ SUBTRACT, 280 
GL_FUNC_SUBTRACT, 280 
GL_MAX, 280 
GL_MIN, 280 
fog equations, 288 
erosion, 1067-1069 
errors, 69 
error flags 
checking for, 70, 77-78 
viewing descriptions of, 70, 82 
GL_STACK_OVERFLOW, 175 
GL_STACK_UNDERFLOW, 175 
NURBS error codes, 533 
Euler angles, 195 
evaluating curves, 496 
evaluators, 491, 521-523 
event-driven programming, 663 
EX2 instruction, 950 
EXP instruction, 952 


expressions, 992-994 
EXT_ extension prefix, 73 
Extended OpenGL, 646-647 
extended pixel formats, 694-696 
extensions, 690-691 
checking for, 72-73 
entended pixel formats, 694 
extension prefixes, 73-74 
GL_ARB_fragment_program, 940,949 
GL_ARB_fragment_shader, 943, 986 
GL_ARB_occlusion_query, 901 
GL_ARB_shader_objects, 943, 986 
GL_ARB_shading_language_100, 943, 986 
GL_ARB_shadow_ambient, 914, 925-926 
GL_ARB_vertex_buffer_object, 864, 872 
GL_ARB_vertex_program, 940, 949 
GL_ARB_vertex_shader, 943, 986 
GL_ATI_vertex_array_object, 866 
GL_EXT_compiled_vertex_array, 866 
GL_EXT_draw_range_elements, 866 
GL_NV_vertex_array_range, 866 
new entrypoints, 692-693 
shaders 
high-level extensions, 943-944 
low-level extensions, 940-942 
simple extensions, 691-692 
WGL extensions, 693-694 
accessing, 693 
entended pixel formats, 694-696 
eye coordinates, 161 
eye linear mapping, 452 
eye linear texture coordinate generation, 917 
eye structure, 214 


F 


Fahrenheit, 39 
fans (triangles), 112 
feedback 
defined, 611 
feedback buffers, 625 
loading and parsing, 632-634 
setting, 625, 634-635 
types, 625 


fog 1131 


feedback data, 625-626 
feedback example 


feedback buffer, loading and parsing, 
632-634 


object selection, 630-632 
objects, labeling for feedback, 627-630 
passthrough markers, 627, 636 
filling polygons (stippling), 123-127, 153 
filtering, 18 
anisotropic filtering, 403, 438-440 
convolution filters 
copying from color buffer, 346, 359-360 


one-dimensional convolution filters, 
347-348, 356 


parameters, 348, 362-363 
separable filters, 346-347, 373 


two-dimensional convolution filters, 345, 
356-357 


mipmap filtering, 402-403 
percentage-closer filtering, 919 
textures, 392-393 
fixed frament processing, 935-936 
fixed functionality, 931, 938-939 
fixed vertex processing 
clipping, 934-935 
lighting, 932-934 
texture coordinate processing, 934 
vertex transformations, 932 
flat shading, 223 
float data type, 988 
FLORIDA program, 512-514 
FLR instruction, 950 
flushing command queue, 54-55, 77, 564 
fog, 19, 286-289, 935-936 
example, 286 
fog application fragment options, 966 


fog coordinate generating vertex shaders, 
1032-1037 


glFog function, 287-289, 298-299 
GL_EXP equation, 288 

GL_EXP2 equation, 288 
GL_LINEAR equation, 288 
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per-fragment fog, 1058-1061 
programmable fragment shaders, 940 
turning on/off, 287 


fonts 


2D fonts, 682-684, 739 
3D fonts, 679-681, 739-741 
3D text rendering, 681 
bitmap fonts 
APL/Carbon APIs, 760-775 
GLX, 812-824 


forcing commands to complete, 76 
foreshortening, 15, 165 

fragment outputs, 960 

fragment shaders, 1051-1052 


color conversion 
color inversion, 1055-1056 
dependent texture lookups, 1058 
grayscale, 1052-1053 
heat signature, 1056, 1058 
sepia tone, 1053, 1055 

high-level shaders 
beach ball, 1092-1094 
checkerboard, 1087-1088 
color inversion, 1055 
diffuse lighting, 1073, 1075 
grayscale conversion, 1053 
heat signature, 1056 
per-fragment fog, 1059 
post-process blur, 1062 
procedural texture mapping, 1084 
sepia-tone conversion, 1054 
three lights, 1077-1078, 1080-1081 
toy ball, 1098-1100 

low-level shaders 
beach ball, 1094-1096 
checkerboard, 1088-1090 
color inversion, 1056 
diffuse lighting, 1074-1077 
grayscale conversion, 1053 
heat signature, 1057 
multiple specular lights, 1079 
per-fragment fog, 1060 
post-process blur, 1063-1064 
procedural texture mapping, 1085-1086 


sepia-tone conversion, 1054 
three lights, 1078-1079, 1081-1083 
toy ball, 1100-1102 
per-fragment fog, 1058-1061 
fragment-specific instruction set, 952-953 
frameless windows, 685-686 
frames 
actor frames, 194-195 
frame buffers, 43 
FRC instruction, 950 
frustrums, 31, 180-181, 204 
full-screen rendering 
frameless windows, 685-686 
full-screen windows, 686-689 
full-screen windows, 686-689 
function pointers, loading, 873 
functions. See individual function names 
future of OpenGL, 39-40 


G 


gaming, 36-38 
GDI (Graphics Device Interface), 41 
cards, 36 
device contexts, 648-650 
general polygons, drawing, 123 
Generic OpenGL, 41-42, 644 


geometric primitives. See primitives, drawing 


GetDC function, 661-662 
GetDeviceCaps function, 686 
GetOpenGLPalette function, 676-677 
GetPixelFormat function, 729 

gimbal lock, 195 

gl prefix, 46 

GL_2D constant, 625, 635 

GL_3D constant, 625, 635 
GL_3D_COLOR constant, 625, 635 


GL_3D_COLOR_TEXTURE constant, 625, 635 
GL_4D_COLOR_TEXTURE constant, 625, 635 


GL_ACCUM constant, 289 
GL_ACCUM_BUFFER_BIT constant, 80 
GL_ADD constant, 427, 466 
GL_ADD_SIGNED constant, 466 
GL_ALL_ATTRIB_BITS constant, 80 


GL_ALPHA constant, 310, 377-378, 919 
GL_ALPHA_BIAS constant, 330 
GL_ALPHA_SCALE constant, 329 

GL_ALWAYS constant, 145, 155 
GL_ARB_fragment_program extension, 940, 949 


GL_ARB_fragment_program fragment shader, 
942 


GL_ARB_fragment_shader extension, 943, 986 

GL_ARB_occlusion_query extension, 901 

GL_ARB_shader_objects extension, 943, 986 

GL_ARB_shading_language_100, 943, 986 

GL_ARB_shadow_ambient extension, 914, 
925-926 


GL_ARB_vertex_buffer_object extension, 866, 
872 


GL_ARB_vertex_program extension, 940, 949 
GL_ARB_vertex_program vertex shader, 941 
GL_ARB_vertex_shader extension, 943, 986 
GL_ATI_vertex_array_object extension, 866 
GL_AUXi constant, 147 

GL_BACK constant, 147 

gl_BackColor vertex shader variable, 991 


gl_BackSecondaryColor vertex shader variable, 
991 


GL_BACK_LEFT constant, 147 
GL_BACK_RIGHT constant, 147 
GL_BGR constant, 310, 378 
GL_BGRA constant, 310, 378 
GL_BGRA_EXT constant, 310, 378 
GL_BGR_EXT constant, 310, 378 
GL_BITMAP constant, 311, 378 
GL_BITMAP_TOKEN constant, 626 
GL_BLEND constant, 76, 427 
GL_BLUE constant, 310, 378 
GL_BLUE_BIAS constant, 330 
GL_BLUE_SCALE constant, 329 
GL_BORDER_COLOR constant, 430 
GL_BYTE constant, 311, 378 
GL_C3F_V3F constant, 605 
GL_C4F_N3F_V3F constant, 605 
GL_C4UB_V2F constant, 604 
GL_C4UB_V3F constant, 605 
gl_ClipVertex vertex shader variable, 991 


GL_DYNAMIC_COPY constant 1133 


GL_COEFF constant, 521 

gl_Color shader variable, 991 
GL_COLOR_BUFFER_BIT constant, 80 
GL_COMBINE constant, 427 
GL_COMPARE_R_TO_TEXTURE mode, 919 


GL_COMPRESSED RGBA_S3TC_DXT1 constant, 
442 


GL_COMPRESSED_RGBA_S3TC_DXT3 constant, 
442 


GL_COMPRESSED_RGBA_S3TC_DXTS constant, 
442 


GL_COMPRESSED_RGB_S3TC_DXT1 constant, 
442 


GL_COMPRESSED_TEXTURE_FORMATS constant, 
442 


GL_CONSTANT constant, 466 
GL_CONSTANT_ALPHA constant, 277 
GL_CONSTANT_COLOR constant, 277 
GL_COPY_PIXEL_TOKEN constant, 626 
GL_CULL_FACE constant, 76 
GL_CURRENT_BIT constant, 80 


GL_CURRENT_VERTEX_ATTRIB_ARB constant, 
975 


GL_DECAL constant, 427 

GL_DECR constant, 156 

GL_DECR_WRAP constant, 156 
GL_DEPTH_BIAS constant, 330 
GL_DEPTH_BUFFER_BIT constant, 80 
GL_DEPTH_COMPONENT constant, 310, 378 
GL_DEPTH_COMPONENT16 constant, 913 
GL_DEPTH_COMPONENT24 constant, 913 
GL_DEPTH_COMPONENT32 constant, 913 
GL_DEPTH_SCALE constant, 329 
GL_DEPTH_TEST constant, 76 
GL_DEPTH_TEXTURE_MODE constant, 422, 430 
GL_DITHER constant, 76 

GL_DOMAIN constant, 521 

GL_DOT3_RGB constant, 466 
GL_DOT3_RGBA constant, 466 
GL_DRAW_PIXEL_TOKEN constant, 626 
GL_DST_ALPHA constant, 277 
GL_DST_COLOR constant, 276 
GL_DYNAMIC_COPY constant, 883 
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1134 GL_DYNAMIC_DRAW constant 


GL_DYNAMIC_DRAW constant, 876, 883 
GL_DYNAMIC_READ constant, 883 
GL_ENABLE BIT constant, 80 

GL_EQUAL constant, 145, 155 

GL_EVAL_BIT constant, 80 

GL_EXP constant, 288 

GL_EXP2 constant, 288 
GL_EXT_compiled_vertex_array extension, 866 
GL_EXT_draw_range_elements extension, 866 
GL_EYE_LINEAR constant, 452, 475 
GL_EYE_PLANE constant, 475 

GL_FEEDBACK mode, 615, 638 

GL_FLOAT constant, 311, 378 

GL_FOG constant, 76 

gl_FogCoord vertex shader variable, 991 
gl_FogFragCoord fragment shader variable, 991 
GL_FOG BIT constant, 80 

GL_FOG_COLOR constant, 287, 299 
GL_FOG_COORD_SRC constant, 299 
GL_FOG_DENSITY constant, 299 
GL_FOG_END constant, 287, 299 
GL_FOG_HINT constant, 78 

GL_FOG_MODE constant, 299 
GL_FOG_START constant, 287, 299 
gl_FragColor fragment shader variable, 991 
gl_FragCoord fragment shader variable, 991 
gl_FragDepth fragment shader variable, 991 
GL_FRAGMENT_DEPTH constant, 288 


GL_FRAGMENT_PROGRAM_ARB constant, 
968-976 


GL_FRONT constant, 147 
gl_FrontColor vertex shader variable, 991 
gl_FrontFacing fragment shader variable, 991 


gl_FrontSecondaryColor vertex shader variable, 
991 


GL_FRONT_AND_BACK constant, 147 
GL_FRONT_LEFT constant, 147 
GL_FRONT_RIGHT constant, 147 
GL_FUNC_ADD constant, 280 
GL_FUNC_REVERSE_SUBTRACT constant, 280 
GL_FUNC_SUBTRACT constant, 280 
GL_GENERATE_MIPMAP constant, 430 


GL_GENERATE_MIPMAP_HINT constant, 79 
GL_GEQUAL constant, 145, 155, 928 
GL_GREATER constant, 145, 155, 928 
GL_GREEN constant, 310, 378 
GL_GREEN_BIAS constant, 329 

GL_GREEN_ SCALE constant, 329 
GL_HINT_BIT constant 80 

GL_INCR constant, 156 

GL_INCR_WRAP constant, 156 

GL_INT constant, 311, 378 

GL_INTENSITY constant, 919 
GL_INTERPOLATE constant, 466 
GL_INVALID_ENUM error flag, 70 
GL_INVALID_OPERATION error flag, 70 
GL_INVALID_VALUE error flag, 70 
GL_INVERT constant, 156 

GL_KEEP constant, 156 

GL_LEFT constant, 147 

GL_LEQUAL constant 145 

GL_LEQUAL constant, 155, 919, 928 
GL_LESS constant, 145, 155, 928 
GL_LIGHTING state, 76, 229 
GL_LIGHTING BIT constant, 80 

GL_LIGHTx constant, 76 

GL_LINEAR constant, 288, 402 
GL_LINEAR_ATTENUATION constant, 269 
GL_LINEAR_MIPMAP_LINEAR constant, 402-403 
GL_LINEAR_MIPMAP_NEAREST constant, 402 
GL_LINES primitive. See lines 

GL_LINE_BIT constant, 80 

GL_LINE_LOOP primitive, 102 
GL_LINE_RESET_TOKEN constant, 626 
GL_LINE_SMOOTH constant, 76 
GL_LINE_SMOOTH_HINT constant, 78 
GL_LINE_STIPPLE constant, 76 
GL_LINE_STRIP constant, 102 
GL_LINE_TOKEN constant, 626 
GL_LIST_BIT constant, 80 

GL_LOAD constant, 289 

GL_LUMINANCE constant, 310, 377-378, 919 
GL_LUMINANCE_ALPHA constant, 310, 377-378 
GL_MAP1_COLOR_4 constant, 522 


GL_MAP1_INDEX constant, 522 
GL_MAP1_NORMAL constant, 522 
GL_MAP1_TEXTURE_COORD_1 constant, 523 
GL_MAP1_TEXTURE_COORD 2 constant, 523 
GL_MAP1_TEXTURE_COORD_3 constant, 523 
GL_MAP1_TEXTURE_COORD 4 constant, 523 
GL_MAP1_VERTEX_3 constant, 522 
GL_MAP1_VERTEX_4 constant, 522 
GL_MAP_COLOR constant, 329 
GL_MAP_ STENCIL constant, 329 
GL_MAX constant, 280 
GL_MAX_PROGRAM_ADDRESS_REGISTERS_ARB 
constant, 971 
GL_MAX_PROGRAM_ALU_INSTRUCTIONS_ARB 
constant, 971 
GL_MAX_PROGRAM_ATTRIBS_ARB constant, 971 
GL_MAX_PROGRAM_ENV_PARAMETERS_ARB 
constant, 971 
GL_MAX_PROGRAM_INSTRUCTIONS_ARB 
constant, 970 
GL_MAX_PROGRAM_LOCAL_PARAMETERS_ARB 
constant, 971 
GL_MAX_PROGRAM_NATIVE_ADDRESS_ 
REGISTERS_ARB constant, 971 
GL_MAX_PROGRAM_NATIVE_ALU_ 
INSTRUCTIONS ARB constant, 971 
GL_MAX_PROGRAM_NATIVE_ATTRIBS_ARB 
constant, 971 
GL_MAX_PROGRAM_NATIVE_INSTRUCTIONS __ 
ARB constant, 970 
GL_MAX_PROGRAM_NATIVE_PARAMETERS_ARB 
constant, 971 
GL_MAX_PROGRAM_NATIVE_TEMPORARIES_ 
ARB constant, 970 
GL_MAX_PROGRAM_NATIVE_TEX_ 
INDIRECTIONS ARB constant, 972 
GL_MAX_PROGRAM_NATIVE_TEX_ 
INSTRUCTIONS_ARB constant, 972 
GL_MAX_PROGRAM_PARAMETERS_ARB 
constant, 971 
GL_MAX_PROGRAM_TEMPORARIES_ARB 
constant, 970 
GL_MAX_PROGRAM_TEX_INDIRECTIONS_ARB 
constant, 972 


GL_PASS_THROUGH_TOKEN constant 1135 


GL_MAX_PROGRAM_TEX_INSTRUCTIONS_ARB 
constant, 972 


GL_MIN constant, 280 

GL_MODULATE constant, 427, 435, 466, 919 
GL_MULTISAMPLE BIT constant, 80 
gl_MultiTexCoordn constant, 991 
GL_N3F_V3F constant, 605 

GL_NEAREST constant, 402 


GL_NEAREST_MIPMAP_LINEAR constant, 
402-403 


GL_NEAREST_MIPMAP_NEAREST constant, 402 
GL_NEVER constant, 145, 155, 928 

GL_NONE constant, 147 

gl_Normal vertex shader variable, 991 
GL_NORMAL_MAP constant, 453, 475 
GL_NOTEQUAL constant, 145, 155, 928 
GL_NO_ERROR flag, 70 


GL_NUM_COMPRESSED_TEXTURE_FORMATS 
constant, 442 


GL_NV_vertex_array_range extension, 866 
GL_OBJECT_LINEAR constant, 450, 475 
GL_OBJECT_PLANE constant, 475 

GL_ONE constant, 276 


GL_ONE_MINUS_CONSTANT_ALPHA constant, 
277 


GL_ONE_MINUS_CONSTANT_COLOR constant, 
277 


GL_ONE_MINUS_DST_ALPHA constant, 277 
GL_ONE_MINUS_DST_COLOR constant, 276 
GL_ONE_MINUS_SRC_ALPHA constant, 277, 466 
GL_ONE_MINUS_SRC_COLOR constant, 276, 466 
GL_ORDER constant, 521 

GL_OUT_OF_MEMORY error flag, 70 
GL_PACK_ALIGNMENT constant, 310, 369 
GL_PACK_IMAGE_HEIGHT constant, 310 
GL_PACK_LSB_FIRST constant, 309, 369 
GL_PACK_ROW_LENGTH constant, 309, 369 
GL_PACK_SKIP_IMAGES constant, 310 
GL_PACK_SKIP_PIXELS constant, 309, 369 
GL_PACK_SKIP_ROWS constant, 309, 369 
GL_PACK_SWAP_BYTES constant, 309, 369 
GL_PASS_THROUGH_TOKEN constant, 626-627 
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GL_PERSPECTIVE_CORRECTION_HINT constant, 
78 
GL_PIXEL_MODE BIT constant, 80 
GL_POINTS primitive. See points 
gl_PointSize vertex shader variable, 991 
GL_POINT_BIT constant, 80 
GL_POINT_SMOOTH constant, 76 
GL_POINT_SMOOTH_HINT constant, 78 
GL_POINT_TOKEN constant, 626 
GL_POLYGON constant, 123 
GL_POLYGON BIT constant, 80 
GL_POLYGON_SMOOTH constant, 76 
GL_POLYGON_SMOOTH_HINT constant, 78 
GL_POLYGON_STIPPLE_BIT constant, 80 
GL_POLYGON_TOKEN constant, 626 
gl_Position vertex shader variable, 991 
GL_POST_COLOR_MATRIX_ALPHA_BIAS con- 
stant, 330 
GL_POST_COLOR_MATRIX_ALPHA_SCALE 
constant, 330 
GL_POST_COLOR_MATRIX_BLUE_BIAS constant, 
330 
GL_POST_COLOR_MATRIX_BLUE_SCALE 
constant, 330 
GL_POST_COLOR_MATRIX_GREEN_BIAS 
constant, 330 
GL_POST_COLOR_MATRIX_GREEN_SCALE 
constant, 330 
GL_POST_COLOR_MATRIX_RED_BIAS constant, 
330 
GL_POST_COLOR_MATRIX_RED_SCALE constant, 
330 
GL_POST_CONVOLUTION_ALPHA_BIAS 
constant, 330 
GL_POST_CONVOLUTION_ALPHA_SCALE 
constant, 330 
GL_POST_CONVOLUTION_BLUE_BIAS constant, 
330 
GL_POST_CONVOLUTION_BLUE_SCALE 
constant, 330 
GL_POST_CONVOLUTION_GREEN_BIAS 
constant, 330 
GL_POST_CONVOLUTION_GREEN_SCALE 
constant, 330 


GL_POST_CONVOLUTION_RED_BIAS constant, 
330 


GL_POST_CONVOLUTION_RED_SCALE constant, 
330 
GL_PREVIOUS constant, 466 
GL_PRIMARY_COLOR constant, 466 
GL_PROGRAM_ADDRESS_REGISTERS_ARB 
constant, 971 
GL_PROGRAM_ALU_INSTRUCTIONS_ARB 
constant, 971 
GL_PROGRAM_ATTRIBS_ARB constant, 971 
GL_PROGRAM _BINDING ARB constant, 970 
GL_PROGRAM_FORMAT_ARB constant, 970 
GL_PROGRAM_INSTRUCTIONS_ARB constant, 
970 
GL_PROGRAM_LENGTH_ARB constant, 970 
GL_PROGRAM_NATIVE_ADDRESS_REGISTERS_ 
ARB constant, 971 
GL_PROGRAM_NATIVE_ALU_INSTRUCTIONS __ 
ARB constant, 971 
GL_PROGRAM_NATIVE_ATTRIBS_ARB constant, 
971 
GL_PROGRAM_NATIVE_INSTRUCTIONS_ARB 
constant, 970 
GL_PROGRAM_NATIVE_PARAMETERS_ARB 
constant, 971 
GL_PROGRAM_NATIVE_TEMPORARIES_ARB 
constant, 970 
GL_PROGRAM_NATIVE_TEX_INDIRECTIONS_ARB 
constant, 972 
GL_PROGRAM_NATIVE_TEX_INSTRUCTIONS _ 
ARB constant, 972 
GL_PROGRAM_PARAMETERS_ARB constant, 970 
GL_PROGRAM_TEMPORARIES ARB constant, 
970 
GL_PROGRAM_TEX_INDIRECTIONS_ARB 
constant, 972 


GL_PROGRAM_TEX_INSTRUCTIONS_ ARB 
constant, 971 


GL_PROGRAM_UNDER_NATIVE_LIMITS_ARB 
constant, 971 


GL_PROXY_TEXTURE_1D constant, 377 
GL_PROXY_TEXTURE_2D constant, 377 
GL_PROXY_TEXTURE_3D constant, 377 
GL_QUADS primitive, 122 


GL_QUAD_STRIP primitive, 123 
GL_READ_ONLY constant, 877, 888 
GL_READ_WRITE constant, 877, 889 
GL_RED constant, 310, 378 
GL_RED_BIAS constant, 329 
GL_RED_SCALE constant, 329 
GL_REFLECTION_MAP constant, 453, 456, 475 
GL_RENDER constant, 614-615, 638 
GL_REPLACE constant, 156, 427, 466 
GL_RETURN constant, 289 

GL_RGB constant, 310, 377-378 
GL_RGBA constant, 310, 377-378 
GL_RIGHT constant, 147 


GL_SAMPLE_ALPHA_TO_COVERAGE constant, 
285 


GL_SAMPLE_ALPHA_TO_ONE constant, 285 
GL_SAMPLE_COVERAGE constant, 285 
GL_SCISSOR_BIT constant, 80 
GL_SCISSOR_TEST constant, 76 
gl_SecondaryColor shader variable, 991 
GL_SELECT constant, 638 

GL_SHORT constant, 311, 378 
GL_SPHERE_MAP constant, 452, 475 
GL_SPOT_CUTOFF constant, 269 
GL_SPOT_DIRECTION constant, 269 
GL_SPOT_EXPONENT constant, 269 
GL_SRC_ALPHA constant, 276, 466 
GL_SRC_ALPHA_SATURATE constant, 277 
GL_SRC_COLOR constant, 276, 466 
GL_STACK_OVERFLOW error, 70, 175 
GL_STACK_UNDERFLOW error, 70, 175 
GL_STATIC_COPY constant, 883 
GL_STATIC_DRAW constant, 876, 883 
GL_STATIC_READ constant, 883 
GL_STENCIL_BUFFER_BIT constant, 80 
GL_STENCIL_INDEX constant, 310, 378 
GL_STENCIL_TEST constant, 76 
GL_STREAM_COPY constant, 884 
GL_STREAM_DRAW constant, 876, 884 
GL_STREAM_READ constant, 884 
GL_SUBTRACT constant, 466 
GL_T2F_C3F_V3F constant, 605 


GL_TEXTURE_MAX_LEVEL constant 1137 


GL_T2F_C4F_N3F_V3F constant, 605 
GL_T2F_C4UB_V3F constant, 605 
GL_T2F_N3F_V3F constant, 605 
GL_T2F_V3F constant, 605 
GL_T4F_C4F_N3F_V4F constant, 605 
GL_T4F_V4F constant, 605 
GL_TABLE_TO_LARGE error flag, 70 
gl_TexCoord shader variable, 991 
GL_TEXTURE constant, 466 
GL_TEXTURE_1D constant, 377 
GL_TEXTURE_2D constant, 377 
GL_TEXTURE_3D constant, 377 
GL_TEXTURE_ALPHA_SIZE constant, 421 


GL_TEXTURE_BASE_LEVEL constant, 401, 422, 
429 


GL_TEXTURE_BIT constant, 80 
GL_TEXTURE_BLUE_ SIZE constant, 421 
GL_TEXTURE_BORDER constant, 421 
GL_TEXTURE_BORDER_COLOR constant, 422 


GL_TEXTURE_COMPARE FUNC constant, 422, 
430 


GL_TEXTURE_COMPARE_ MODE constant, 422, 
430 


GL_TEXTURE_COMPONENTS constant, 421 
GL_TEXTURE_COMPRESSED constant, 441 


GL_TEXTURE_COMPRESSED_IMAGE_SIZE 
constant, 421, 441 


GL_TEXTURE_COMPRESSION_HINT constant, 72, 
442 


GL_TEXTURE_CUBE_MAP constant, 76 
GL_TEXTURE_DEPTH constant, 421 
GL_TEXTURE_GENERATE_MIPMAP constant, 422 
GL_TEXTURE_GEN_x state, 76 
GL_TEXTURE_GREEN_SIZE constant, 421 
GL_TEXTURE_HEIGHT constant, 421 
GL_TEXTURE_INTENSITY_SIZE constant, 421 


GL_TEXTURE_INTERNAL_FORMAT constant, 421, 
441 


GL_TEXTURE_LOD_BIAS constant, 404-405, 422 
GL_TEXTURE_LUMINANCE SIZE constant, 421 
GL_TEXTURE_MAX_FILTER constant, 422, 429 


GL_TEXTURE_MAX_LEVEL constant, 401, 422, 
429 
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GL_TEXTURE_MAX_LOD constant, 422, 429 
GL_TEXTURE_MIN_FILTER constant, 422, 429 
GL_TEXTURE_MIN_LOD constant, 422, 429 
GL_TEXTURE_PRIORITY constant, 422, 430 
GL_TEXTURE_RED_SIZE constant, 421 
GL_TEXTURE_RESIDENT constant, 422 
GL_TEXTURE_WIDTH constant, 421 
GL_TEXTURE_WRAP_R constant, 422, 430 
GL_TEXTURE_WRAP_S constant, 422, 429 
GL_TEXTURE_WRAP_T constant, 422, 429 
GL_TEXTURE_xD constant, 76 
GL_TRANSFORM BIT constant, 80 
GL_TRIANGLES primitive. See triangles 
GL_TRIANGLE_FAN primitive, 112 
GL_TRIANGLE_STRIP primitive, 111 
GL_UNPACK_ALIGNMENT constant, 310, 369 
GL_UNPACK_IMAGE_HEIGHT constant, 310 
GL_UNPACK_LSB_FIRST constant, 309, 369 
GL_UNPACK_ROW_LENGTH constant, 309, 369 
GL_UNPACK_SKIP_IMAGES constant, 310 
GL_UNPACK_SKIP_PIXELS constant, 309, 369 
GL_UNPACK_SKIP_ROWS constant, 309, 369 
GL_UNPACK_SWAP_BYTES constant, 309, 369 
GL_UNSIGNED_BYTE constant, 311, 378 


GL_UNSIGNED_BYTE_2_3_3_REV constant, 311, 
378 

GL_UNSIGNED_BYTE_3_2 2 constant, 311, 378 

GL_UNSIGNED_INT constant, 311, 378 

GL_UNSIGNED_INT_10_10_10_2 constant, 311, 
378 

GL_UNSIGNED_INT_2_10_10_10_REV constant, 
311, 378 

GL_UNSIGNED_INT_8 8 8 8 constant, 311, 378 


GL_UNSIGNED_INT_8 8 8 8 REV constant, 311, 


311, 378 


GL_UNSIGNED_SHORT_4 4 4 4 constant, 311, 
378 
STAN tcesinc, 87% Lie 


GL_UNSIGNED_SHORT_S_5_5_1 constant, 311, 
378 


GL_UNSIGNED_SHORT_5 6_5 constant, 311, 378 


GL_UNSIGNED_SHORT_5S_6_5_REV constant, 
311, 378 


GL_V2F constant, 604 
GL_V3F constant, 604 
gl_Vertex vertex shader variable, 991 


GL_VERTEX_ATTRIB_ARRAY_ENABLED_ARB 
constant, 974 


GL_VERTEX_ATTRIB_ARRAY_NORMALIZED_ARB 
constant, 974 


GL_VERTEX_ATTRIB_ARRAY_SIZE_ARB constant, 
974 


GL_VERTEX_ATTRIB_ARRAY_STRIDE_ARB 
constant, 974 


GL_VERTEX_ATTRIB_ARRAY_TYPE_ARB constant, 
974 


GL_VERTEX_PROGRAM_ARB constant, 968-976 
GL_VIEWPORT_BIT constant, 80 
GL_WRITE_ONLY constant, 877, 889 
GL_ZERO constant, 156, 276 
gl.h header file, 45 
glAccum function, 289-290, 295 
glActiveTexture function, 458, 467-468 
glAlphaFunc function, 293-294, 928 
glAreTexturesResident function, 415-417 
glArrayElement function, 581, 596 
glAttachObjectARB function, 984, 999 
glBegin function, 142 
GL_LINES parameter, 100 
GL_LINE_LOOP parameter, 102 
GL_LINE_STRIP parameter, 102 
GL_POINTS parameter, 93 
GL_TRIANGLES parameter, 109 
GL_TRIANGLE_FAN parameter, 112 
GL_TRIANGLE_STRIP parameter, 111 
glBeginQuery function, 896, 903 
glBindAttribLocationARB function, 1000 
glBindBuffer function, 874, 882 
glBindProgramARB function, 946, 967 
glBindTexture function, 405, 417 
GLbitfield data type, 46 
glBitmap function, 308, 353 


glBlendColor function, 295-296 
glBlendEquation function, 279, 296 
glBlendFunc function, 276-277, 296-297 
glBlendFuncSeparate function, 280, 297 
GLboolean data type, 46 

glBufferData function, 875-876, 883 
glBufferSubData function, 875, 884 

GLbyte data type, 46, 1114 

glCaliList function, 566, 597 

glCaliLists function, 566, 597-598, 681, 761, 812 
GLclampd data type, 46 

GLclampf data type, 46 

GLClampx data type, 1114 

glClear function, 54 

glClearAccum function, 297-298 

glClearColor function, 53-54, 75 
glClearDepth function, 143 

glClearStencil function, 143 
glClearStencilgiClearStencil function, 144 
glClientActiveTexture function, 468 

glColor function, 220-223, 231, 266 
glColor3f function, 57 

g!ColorMask function, 267, 292, 298, 929 
glColorMaterial function, 231, 268 
glColorPointer function, 580, 598-599 
glColorSubTable function, 344, 354 
glColorTable function, 341-342, 354-355 
glCompileShaderARB function, 983-984, 1000 
glCompressedTexImage function, 443, 468-469 


glCompressedTexSubImage function, 443, 
469-470 


glConvolutionFilter1D function, 347-348, 356 
glConvolutionFilter2D function, 345, 356-357 


glConvolutionParameter function, 348, 357, 
362-363 


glCopyColorSubTable function, 358 
glCopyColorTable function, 343, 358-359 
glCopyConvolutionFilter1D function, 359 
glCopyConvolutionFilter2D function, 346, 359 
glCopyPixels function, 317, 360-361, 1115 
glCopyTexImage1D function, 379, 417-418 
glCopyTexImage2D function, 379, 417-418, 913 


glEvalCoord function 1139 


glCopyTexSubImage function, 380, 929 
glCreateProgramObjectARB function, 1001 
glCreateShaderObjectARB function, 982, 1001 
glCullFace function, 144 
glDeleteBuffers function, 874, 885 
glDeleteLists function, 565, 599 
glDeleteObjectARB function, 982, 984, 1002 
glDeleteProgramsARB function, 948, 968 
glDeleteQuery function, 903-904 
glDeleteTextures function, 405, 419-420 
glDepthFunc function, 144-145 
glDepthMask function, 135, 145-146 
glDepthRange function, 146 
glDetachObjectARB function, 984, 1002 
g!Disable function, 68, 75-76, 284, 443 
glDisableClientState function, 602 
glDisableVertexAttribArrayARB function, 968 
GLdouble data type, 46, 1113 
glDrawArrays function, 582, 599-600, 870-871 
g!DrawBuffer function, 132, 146-147, 317, 1115 
glDrawElements function, 585, 600, 881 
glDrawPixels function, 310, 361, 377, 564, 1115 
glDrawRangeElements function, 586, 600-601 
glEdgeFlag function, 129, 147 
glEdgeFlagPointer function, 580, 601-602 
glEnable function, 68, 75-76, 229-231, 238, 276, 
280, 284, 443 
glEnableClientState function, 602 
glEnableVertexAttribArrayARB function, 958, 
969 
glEnd function, 148 
GL_LINES parameter, 100 
GL_LINE_LOOP parameter, 102 
GL_LINE_STRIP parameter, 102 
GL_POINTS parameter, 93 
GL_TRIANGLES parameter, 109 
GL_TRIANGLE_FAN parameter, 112 
GL_TRIANGLE_STRIP parameter, 111 
glEndList function, 565, 602-603 
glEndQuery function, 897, 904 
GLenum data type, 46 
glEvalCoord function, 495, 519 
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glEvalMesh function, 519 
glEvalPoint function, 520 
glext.h header file, 74 
glFeedback function, 625, 634-635 
glFeedbackBuffer function, 626 
glFinish function, 76, 133 
GLFixed data type, 1114 
GLfloat data type, 46, 1114 
glFlush function, 54-55, 77, 133, 564 
glFog function, 287-289, 298-299 
glFogCoordPointer function, 580, 603 
GLFrame data structure, 194 
glFrontFace function, 111, 148 
glFrustum function, 181, 204 
glGenBuffers function, 874, 885 
glGenLists function, 565, 603-604, 760, 812 
glGenProgramsARB function, 946, 969 
glGenQueries function, 896, 904 
glGenTextures function, 405, 420 
glGet function, 175 
glGetActiveAttribARB function, 1003-1004 
glGetActiveUniformARB function, 1004 
glGetAttachedObjectsARB function, 1005 
glGetAttribLocationARB function, 1006 
glGetBooleanv function, 68, 77 
glGetBufferParameteriv function, 881, 885 
glGetBufferPointerv function, 881, 886 
glGetBufferSubData function, 881, 887 
glGetColorTable function, 363 
glGetColorTableParameter function, 343, 
355-356, 363-364 
glGetCompressedTexImage function, 442, 471 
glGetConvolutionFilter function, 362 
glGetDoublev function, 68, 77 
glGetError function, 70, 77-78 
glGetFloatv function, 68, 77, 438 
glGetHandleARB function, 1006 
glGetHistogram function, 350, 364-365 
glGetHistogramParameter function, 365 
glGetInfoLogARB function, 1006 
glGetintegerv function, 68, 77 
glGetLight function, 268 


glGetMap function, 520 

glGetMaterial function, 269 

glGetMinmax function, 352, 365-366 
glGetObjectParameter*vARB function, 1007 
glGetObjectParameterivARB function, 984 
glGetPolygonStipple function, 149 
glGetProgramEnvParameter*ARB function, 966 
glGetProgramEnvParameter*vARB function, 972 
glGetProgramivARB function, 963-965, 970-972 
glGetProgramLocalParameter*ARB function, 966 


glGetProgramLocalParameter*vARB function, 
973 


glGetProgramStringARB function, 966, 973 
glGetQueryiv function, 905 
glGetQueryObjectiv function, 900, 905 
glGetSeparableFilter function, 366 
glGetShaderSourceARB function, 1008 
glGetString function, 71, 78, 655, 693, 901 
glGetTexImage function, 423, 442 
glGetTexLevelParameter function, 420-421 
glGetTexLevelParameteriv function, 441-442 
glGetTexParameter function, 422 
glGetUniform*vARB function, 1009 
glGetUniformLocationARB function, 1010 
glGetVertexAttrib*ARB function, 966 
glGetVertexAttrib*vARB function, 974 


glGetVertexAttribPointervARB function, 966, 
975 


glHint function, 71, 78-79, 283, 442 
glHistogram function, 349, 366-367 
glinitNames function, 614, 635-636 

GLint data type, 46 

glinterleavedArrays function, 586, 604-605 
glisBuffer function, 881, 888 

gllsEnabled function, 68, 79 

glisList function, 605-606 

gllsProgramARB function, 966, 975 
glisQuery function, 902, 906 

glisTexture function, 423-424 

glLight function, 250-251, 270 
glLightModel function, 229-230, 271-272, 437 
glLineStipple function, 106-108, 149 


glLineWidth function, 104-106, 150 
glLinkProgramARB function, 985, 1010 
glListBase function, 606, 681, 761, 812 
glLoadidentity function, 61, 90, 174, 204, 618 
glLoadMatrix function, 188, 205 
glLoadName function, 627 

glLoadNames function, 614, 636 
glLoadTransposeMatrix function, 189, 205 
glLogicOp function, 292-293, 299 

glMap function, 521-523 

glMapBuffer function, 876-877, 888 
glMapGrid function, 496, 523-524 
g!Material function, 230-233, 272 
g!MatrixMode function, 90, 206, 340-341, 382 
g!lMinmax function, 352, 367 
giMultiDrawArrays function, 586 
giMultiDrawElements function, 606-607 
giMultiTexCoord function, 459, 471-473 
glMultiTexCoord2f function, 459 
glMultMatrix functions, 193 
glMultTransposeMatrix function, 207 
glNewList function, 565, 607-608 
glNormal function, 237, 273 
glNormal!Pointer function, 580, 608 
glOrtho function, 60-62, 79-80, 90, 178 
glPassThrough function, 627, 632, 636 
glPixelMap function, 333-334, 368 


glPixelStore function, 125, 309-310, 368-369, 
1115 


glPixelTransfer function, 329-333, 369-370, 1115 
glPixelZoom function, 327-328, 370, 1115 
glPointSize function, 97-100, 151 
glPolygonMode function, 121, 129, 152, 1115 
glPolygonOffset function, 152-153, 926, 930 
glPolygonStipple function, 123-127, 153 
glPopAttrib function, 69, 80, 761, 812 
g!PopMatrix function, 92, 96, 178, 201-202, 207 
glPopName function, 637 

g!PrioritizeTextures function, 416, 424 
glProgramEnvParameter*ARB function, 976 
glProgramEnvParameter4*ARB function, 956 


glShaderSourceARB function 1141 


glProgramLocalParameter*ARB function, 976 


glProgramStringARB function, 946-948, 963-965, 
977 


glPushAttrib function, 69, 80, 761, 812 
glPushMatrix function, 92, 96, 178, 201-202, 208 
glPushName function, 614, 637 


glRasterPos function, 307-308, 370-371, 761, 
812 


glReadBuffer function, 317, 1115 


glReadPixels function, 316-317, 371-372, 564, 
826, 833, 1115 


glRect function, 57-58, 81 
GLRECT program 
clipping volumes, 58-62, 79-80 
device contexts, creating, 661-663 
OpenGL rendering context 
creating, 663-666 
deleting, 663-667 
initializing, 666-667 
shutting down, 667 
rectangles, drawing, 57-58, 81 
screen, clearing, 55-56 
viewports, 58-59, 81-82 
windows 
creating, 658, 660-661 
scaling, 58, 85 
WM_PAINT message, 668-669 
WM_SIZE message, 667 
WM_TIMER message, 668 


glRenderMode function, 614, 616, 619, 625, 
637-638 


glResetHistogram function, 372 
glResetMinmax function, 372 

glRotate function, 92, 96, 170, 178 
glSampleCoverage function, 285, 300 
glScale function, 238, 917 

g!Scissor function, 135-136, 154 
glSecondaryColor function, 437, 473-474 
glSecondaryColorPointer function, 580, 608-609 
glSelectBuffer function, 616, 638 
glSeparableFilter2D function, 346-347, 373 
glShadeModel function, 116, 223, 274 
glShaderSourceARB function, 982-983, 1011 
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GLshort data type, 46, 1114 

GLsizei data type, 46 

GLSL fragment shader, 944 

GLSL vertex shader, 943 

glStencilFunc function, 136-138, 154-155 

glStencilMask function, 140, 155 

glStencilOp function, 138-140, 155-156 

gltApplyActorTransform function, 201 

gltApplyCameraTransform function, 196, 201 

gltDegToRad function, 190 

gltDrawTorus function, 192 

glTexCoord function, 380-382, 424-426, 458-459 

glTexCoordPointer function, 580, 609-610 

glTexEnv function, 390-392, 404, 426-427, 
465-467 

glTexGen function, 474, 917 

glTexGenf function, 444, 452, 474 


glTexImage function, 376-379, 389, 401, 
427-429, 440-441, 455, 875, 1115 


glTexParameter function, 392, 429-430, 439, 
918-920 


glTexParameteri function, 401 


glTexSubImage function, 379-380, 418-419, 
430-431, 875 


gltGetExtensionPointer function, 73-74, 693, 873 
gltGetMatrixFromFrame function, 194 
gltGetNormalVector function, 243 
gitinitFrame function, 200 
glitlsExtensionSupported function, 438 
gitIlsExtSupported function, 73 
gltLoadTGA function, 314-316, 389 
gltMakeShadowMatrix function, 259-260 
GLTMatrix data type, 190 
gltMoveFrameForward function, 202 
gltMultiplyMatrix function, 192 
gitMultMatrix function, 206 


glTranslate function, 169, 172, 178, 209, 681, 
917 


gltRotateFrameLocalY function, 202 
gltRotationMatrix function, 190 
gltStopwatchRead function, 568 
gltStopwatchReset function, 568 


gltTransformPoint function, 191 
gltWriteTGA function, 317-318, 320 
GLU_AUTO_LOAD_MATRIX constant, 535 
GLU_CULLING constant, 535 
GLU_DISPLAY_MODE constant, 535 
GLU_FILL constant, 479 

GLU_FLAT constant, 540 

GLU_LINE constant, 479 

GLU_NONE constant, 540 
GLU_NURBS_ERROR* constants, 533 
GLU_PARAMETRIC_TOLERANCE constant, 535 
GLU_PATH_LENGTH constant, 535 
GLU_POINT constant, 479 
GLU_SAMPLING_METHOD constant, 535 
GLU_SAMPLING_TOLERANCE constant, 535 
GLU_SILHOUETTE constant, 479 
GLU_TESS_BEGIN constant, 543 
GLU_TESS_BEGIN_DATA constant, 543 
GLU_TESS_BOUNDARY_ONLY constant, 545 
GLU_TESS_COMBINE constant, 543 
GLU_TESS_COMBINE_DATA constant, 543 
GLU_TESS_EDGE_FLAG constant, 544 
GLU_TESS_EDGE_FLAG_ DATA constant, 544 
GLU_TESS_END constant, 544 
GLU_TESS_END_DATA constant, 544 
GLU_TESS_ERROR constant, 544 
GLU_TESS_TOLERANCE constant, 545 
GLU_TESS_VERTEX constant, 544 
GLU_TESS_VERTEX_DATA constant, 544 
GLU_TESS_WINDING_RULE constant, 545 
GLU_U_STEP constant, 535 

GLU_V_STEP constant, 535 

glu.h header file, 45 

glu32.dll, 44 

gluBeginCurve function, 524 
gluBeginSurface function, 504, 524 
gluBeginTrim function, 505-508, 525 
gluBuild1DMipmapLevels function, 404, 431-432 
gluBuild1DMipmaps function, 432 
gluBuild2DMipmapLevels function, 404 
gluBuild2DMipmaps function, 433 
gluBuild3DMipmapLevels function, 404 


gluBuild3DMipmaps function, 433 
gluBuildMipmaps function, 403, 432-433 
GLubyte data type, 46, 1114 

gluCylinder function, 481, 525-526 
gluDeleteNurbsRenderer function, 503, 526 
gluDeleteQuadric function, 526 
gluDeleteTess function, 527 

gluDisk function, 483, 527-528 
gluEndCurve function, 528 

gluEndSurface function, 504, 528 
gluEndTrim function, 505-508, 529 
gluErrorString function, 70, 82 
gluGetNurbsProperty function, 529 
gluGetString function, 71 

GLuint data type, 46 
gluLoadSamplingMatrices function, 530 
gluLookAt function, 196, 209, 908 
gluNewNurbsRenderer function, 503, 530 
gluNewQuadric function, 479, 531 
gluNewTess function, 531 

glUniform*ARB function, 1011-1012 
glUnmapBuffer function, 878, 889 
gluNurbsCallback function, 531 
gluNurbsCurve function, 508, 534 
gluNurbsProperty function, 504, 534-536 
gluNurbsSurface function, 504-505, 536-537 
gluOrtho2D function, 210 

gluPartialDisk function, 537 

gluPerspective function, 181, 210, 909 
gluPickMatrix function, 611, 618-620, 639 
gluPwiCurve function, 508, 538 
gluQuadricCallback function, 539 
gluQuadricDrawStyle function, 479, 539-540 
gluQuadricNormals function, 480, 540 
GLUQuadricObj data type, 479 
gluQuadricOrientation function, 480, 540-541 
gluQuadricTexture function, 480, 541 
glUseProgramObject function, 986, 1013 
GLushort data type, 46 

gluSphere function, 480-481, 541-542 


GLUT (OpenGL utility toolkit), 48-49, 52, 84, 
744, 796 


glutKeyboardFunc function 1143 


glutCreateWindow function, 52, 82 
glutDisplayFunc function, 52, 82-83 
gluTessBeginContour function, 512, 542 
gluTessBeginPolygon function, 512, 542 
gluTessCallback function, 510-512, 543-544 
gluTessEndContour function, 512, 544 
gluTessEndPolygon function, 512, 544 
gluTessProperty function, 545 
gluTessVertex function, 512, 546 
GLUT_ACCUM mask value, 83 
GLUT_DEPTH mask value, 83 
GLUT_DOUBLE mask value, 83 
GLUT_KEY_DOWN key value, 87 
GLUT_KEY_END key value, 87 
GLUT_KEY_F1 key value, 86 
GLUT_KEY_F10 key value, 87 
GLUT_KEY_F11 key value, 87 
GLUT_KEY_F12 key value, 87 
GLUT_KEY_F2 key value, 86 
GLUT_KEY_F3 key value, 86 
GLUT_KEY_F4 key value, 86 
GLUT_KEY_FS key value, 86 
GLUT_KEY_F6 key value, 87 
GLUT_KEY_F7 key value, 87 
GLUT_KEY_F8 key value, 87 
GLUT_KEY_F9 key value, 87 
GLUT_KEY_HOME key value, 87 
GLUT_KEY_INSERT key value, 87 
GLUT_KEY_LEFT key value, 87 
GLUT_KEY_PAGE_ DOWN key value, 87 
GLUT_KEY_PAGE _UP key value, 87 
GLUT_KEY_RIGHT key value, 87 
GLUT_KEY_UP key value, 87 
GLUT_LUMINANCE mask value, 83 
GLUT_MULTISAMPLE mask value, 83 
GLUT_RGBA flag, 52, 83 
GLUT_SINGLE flag, 52, 83 
GLUT_STENCIL mask value, 83 
GLUT_STEREO mask value, 83 


glutinitDisplayMode function, 51, 67, 83, 
132-134, 137, 284, 292 
glutKeyboardFunc function, 84 
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glutMainLoop function, 52, 84 
glutMouseFunc function, 84-85 
glutPostRedisplay function, 85 
glutReshapeFunc function, 58, 85 
glutSetWindowTitle function, 619 
glutSolidSphere function, 172, 250 
glutSolidTeapot function, 86 
glutSpecialFunc function, 86-87 
glutSwapBuffers function, 67, 87, 132 
glutTimerFunc function, 63, 87-88 
glutWireCube function, 169 
glutWireTeapot function, 86 
glValidateProgramARB function, 985-986, 1013 
glVertex function, 92-93, 156, 581, 958 
glVertexAttrib*ARB function, 958, 978-979 
glVertexAttribPointerARB function, 958, 979 
glVertexPointer function, 580, 610, 874 
GLView program, 654 
glViewport function, 59, 81-82, 168 
GLwDrawingArea widget, 840-841 
GLwDrawingAreaMakeCurrent function, 842 
GLwDrawingAreaSwapBuffers function, 843 
glWindowPos function, 308, 335, 374 
GLwMDrawingArea widget, 840-841 
GLwNexposeCallback callback, 841 
GLwNginitCallback callback, 842 
GLwNinputCallback callback, 842 
GLwNresizeCallback callback, 842 
GLX, 793 
bitmap fonts, 812-824 
checking support for, 797 
context management, 800 
GLUT library, 796 
Mesa library, 797 
Motif library, 839 
callbacks, 841-842 
GLw library functions, 842 
GLwDrawingArea widget, 840-841 
GLwMDrawingArea widget, 840-841 
sample program, 843-855 


offscreen rendering 
GLX pixmaps, 825-832 
Pbuffers, 832-839 
OpenGL windows, 800-801 
server connections, 798 
Summit, 797 
versions, 797 
visual attribute list constants, 798-800 
X servers, 798 
X11 libraries, 793-796 
Xfree86 project, 796-797 
Xlib spinning cube program 
bitmap fonts, 812-824 
initial code listing, 801-812 
GLX_ACCUM_ALPHA_SIZE constant, 798 
GLX_ACCUM_BLUE_SIZE constant, 798 
GLX_ACCUM_GREEN SIZE constant, 798 
GLX_ACCUM_RED._ SIZE constant, 798 
GLX_ALPHA_SIZE constant, 798 
GLX_AUX_BUFFERS constant, 798 
GLX_BLUE_SIZE constant, 799 
GLX_BUFFER_SIZE constant, 799 
GLX_DEPTH_SIZE constant, 799 
GLX_DOUBLEBUFFER constant, 799 
GLX_GREEN_SIZE constant, 799 
GLX_LEVEL constant, 799 
GLX_RED_SIZE constant, 799 
GLX_RGBA constant, 799 
GLX_STENCIL_SIZE constant, 799 
GLX_STEREO constant, 799 
GLX_USE_GL constant, 799 
glXChooseFBConfig function, 832, 855 
glXChooseVisual function, 801, 825, 855 
g!XCreateContext function, 800, 826, 856 
glXCreateGLXPixmap function, 826, 856 
glXCreateNewContext function, 833, 857 
g|XCreatePbuffer function, 833, 857 
glXDestroyContext function, 800, 858 
g!XDestroyGLXPixmap function, 858 
g!XDestroyPbuffer function, 859 
glXGetFBConfigs function, 859 
g!XGetVisualFromFBConfig function, 860 


g!XMakeCurrent function, 801, 860 
glXSwapBuffers function, 801, 861 
glXUseXFont function, 812, 861 
GLYPHMETRICSFLOAT structure, 681 
graphics cards 
CGA (Color Graphics Adapter), 215 
EGA (Enhanced Graphics Adapter), 216 
Hercules, 215 
Super-VGA, 216 
VGA (Video Graphics Array), 216 
Graphics Device Interface. See GDI 
graphics. See 2D imaging; 3D graphics 
graphs. See scene graphs 
grayscale conversion, 1052-1053 
grids, 496, 523-524 
groups, attribute groups, 80 


H 


hardware generation of mipmaps, 404 
hardware OpenGL implementations, 42-43 
hardware T&L (transform and lighting), 188 
head of bolt model, 549, 551-554 
headers, 44-45 
heat signatures, 1056, 1058 
Hercules cards, 215 
hidden surface removal, 16, 116-118, 918 
hierarchical picking, 620-624 
high-level fragment shaders 

beach ball, 1092-1094 

checkerboard, 1087-1088 

color inversion, 1055 

diffuse lighting, 1073, 1075 

grayscale conversion, 1053 

heat signature, 1056 

per-fragment fog, 1059 

post-process blur, 1062 

procedural texture mapping, 1084 

sepia-tone conversion, 1054 

three lights, 1077-1078, 1080-1081 

toy ball, 1098-1100 


hints 


high-level shader extensions, 943-944 
high-level vertex shaders, 981-982 
array access, 992 
arrays, 989-990 
built-in variables, 990-991 
compiling, 983-984, 1000 
component selectors, 994 
constructors, 992-994 
creating, 982, 1001 
data types, 988 
deleting, 982, 1002 
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diffuse lighting high-level shader, 1018-1019 


discard statement, 996 
extension setup, 986-987 


fog coordinate generating high-level shader, 


1032-1034 
functions, 996-999 
if/else statements, 995-996 
loops, 995 
operators, 992 


point size generating high-level shader, 
1037-1039 


program objects 
attaching, 984, 999 
creating, 984 
deleting, 984 
detaching, 984, 1002 
enabling/disabling, 986, 1013 
linking, 985, 1010 
validating, 985-986, 1013 
qualifiers, 990 
shader text, 982-983, 1011 
simple high-level shader, 1015-1018 


specular lighting high-level shader, 
1021-1022 


squash-and-stretch high-level shader, 
1040-1043 


structures, 988-989 


three-colored lights high-level shader, 
1024-1026, 1029 


vertex blending high-level shader, 1043-1048 


highlights, 244 
hints, 78-79 


How can we make this index more useful? Email us at indexes@samspublishing.com 


1146 histograms 


histograms, 349-352 
collecting data, 350, 364-365 
defining, 349, 366-367 
minmax operations, 352, 365-367 
parameters, 365 

history of OpenGL, 33-34 
API wars, 37 
ARB (Architecture Review Board), 34-35 
Direct3D, 38 
DirectX, 36 
Fahrenheit, 39 
gaming, 37-38 
IRIS GL, 34 
licensing and conformance, 35 
Mini-Client Driver (MCD), 38-39 
PC applications, 36-37 

human eye structure, 214 


IBM_ extension prefix, 73 
ID Software, 37 
IDC (Installable Client Driver), 644-645 
identity matrix, 172-174, 204 
IdleFunction function, 668 
if/else statements, 995-996 
image processing, 1061-1062 
blur, 1062-1065 
dilation, 1067-1069 
edge detection, 1070-1072 
erosion, 1067-1069 
sharpen, 1065-1067 
IMAGELOAD program, 312-316 
gltLoadTGA function, 314-316 
RenderScene function, 312-313 
imaging pipeline 
color lookup tables, 341-344 
parameters, 343-344, 354-359, 363 
proxies, 343 
setting up, 341, 354-355 
color matrix, 340-341 
convolutions, 344-346 


combining with other imaging operations, 
345-346 


copying from color buffer, 346, 359-360 


glConvolutionFilter1D function, 347-348, 
356 


glConvolutionFilter2D function, 345, 
356-357 


kernels, 344 


one-dimensional convolution filters, 
347-348, 356 


parameters, 348, 362-363 
separable filters, 346-347, 373 


two-dimensional convolution filters, 345, 
356-357 


histograms, 349-352 
collecting data, 350, 364-365 
defining, 349, 366-367 
minmax operations, 352, 365-367 
parameters, 365 
IMAGING program, 336-339 
imaging subset, 335-337 
color lookup tables, 341-344 
copying, 343, 358-359 
parameters, 343, 363 
proxies, 343, 355-356 
replacing, 344, 354, 358 
setting up, 341, 354-355 
color matrix, 340-341 
convolutions, 344-346 


combining with other imaging operations, 
345-346 


copying from color buffer, 346, 359-360 


glConvolutionFilter1D function, 347-348, 
356 


glConvolutionFilter2D function, 345, 
356-357 


kernels, 344 


one-dimensional convolution filters, 
347-348, 356 


parameters, 348, 362-363 
separable filters, 346-347, 373 


two-dimensional convolution filters, 345, 
356-357 


histograms, 349-352 
collecting data, 350, 364-365 
defining, 349, 366-367 
minmax operations, 352, 365-367 
parameters, 365 
IMAGING sample program, 336, 338-339 
imaging. See 2D imaging 
immediate mode, 25 
in qualifier, 990 
in-line constants, 954-955 
indexed vertex arrays 
creating, 589-594 
glDrawElements function, 585, 600 
glDrawRangeElements function, 586, 600-601 
glInterleavedArrays function, 586, 604-605 
glMultiDrawArrays function, 586 
memory requirements, 588-589, 595-596 
MODELTEST sample program, 586-588 
simple cube example, 582-585 
indirections, 964 
initializing 
buffer objects, 874 
display modes, 83 
name stack, 614, 635-636 
OpenGL, 52 
rendering context, 666-667 
initWithFrame function, 778 
inout qualifier, 990 
input negate modifier, 961 
input swizzle modifier, 961-962 
input/output modifiers 
input negate, 961 
input swizzle, 961-962 
output clamp, 962-963 
output writemask, 962 
Installable Client Driver (IDC), 644-645 
instructions 
ABS, 950 
ADD, 950 
ARL, 952 
CMP, 953 
COS, 953 
DP3, 950 


interactive graphics 


DP4, 950 

DPH, 950 

DST, 950 

EX2, 950 

EXP, 952 

FLR, 950 

FRC, 950 

KIL, 953 

LG2, 950 

LIT, 950 

LOG, 952 

LRP, 953 

MAD, 950 

MAX, 951 

MIN, 951 

MOV, 951 

MUL, 951 

POW, 951 

RCP, 951 

RSQ, 951 

SCS, 953 

SGE, 951 

SIN, 953 

SLT, 951 

SUB, 951 

SWZ, 951 

TEX, 953 

TXB, 953 

TXP, 953 

XPD, 951 
int data type, 988 
intensity of light, 226-227 
interactive graphics 

feedback buffers, 625, 634-635 

feedback data, 625-626 

feedback example 


feedback buffer, loading and parsing, 
632-634 


object selection, 630-632 
objects, labeling for feedback, 627-630 
passthrough markers, 627, 636 
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picking, 617-618 
defined, 611 
gluPickMatrix function, 618-620, 639 
hierarchical picking, 620-624 
primitives, naming, 612-614 
selection buffers, 615-617 
allocating, 616, 638 
feedback, 611 
selection mode, 614-615 
internal texture formats, 377 
InvalidateRect function, 668 
inversion (color), 1055-1056 
IRIS GL, 34 
ivec2 data type, 988 
ivec3 data type, 988 
ivec4 data type, 988 


J-K 


jaggies, 20, 280 


kernels, 344 

keyboards 
glutKeyboardFunc function, 84 
keyboard polling, 203 
non-ASCII keystrokes, 86-87 

Khronos Web site, 1116 

KIL instruction, 953 

Kilgard, Mark, 48 

knot multiplicity, 502 

knots, 502 


L 


labeling objects for feedback, 627-630 
Last In First Out (LIFO), 69 
levels, mip 
generating, 403-404, 431-433 
hardware generation of mipmaps, 404 
loading, 401 
LOD_BIAS, 404-405 
LG2 instruction, 950 


libraries, 44-45 
glu32.dll, 44 
GLUT library, 796 
Mesa, 797 
Motif, 839 
callbacks, 841-842 
GLw library functions, 842 
GLwDrawingArea widget, 840-841 
GLwMDrawingArea widget, 840-841 
sample program, 843-855 
opengl32.dll, 44 
X11 libraries, 793-796 
licensing, 35 
LIFO (Last In First Out), 69 
lighting, 17, 224-225, 229. See also shadows 
adding to materials, 227-228 
ambient light, 225 
calculating effects of, 228 
sample code listing, 232-233 
shadows, 913-914 
Bézier curves, 500 
diffuse lighting, 225 
calculating effects of, 228-229 


diffuse lighting fragment shaders, 
1073-1077 


diffuse lighting vertex shaders, 1018-1021 
shadows, 914 
enabling, 229 
fixed vertex processing, 932, 934 
light intensity and distribution, 226-227 
light particles, 212-213 
light sources, 234-235 
returning information about, 268-269 
setting up, 240-241 
specifying, 250-251, 270 
light viewpoint 
drawing, 908 
rendering, 909-913 
lighting models, 229-230, 271-272 
multiple specular lights, 1077-1083 
normals 
averaging, 248-249 
finding, 238-240 


specifying, 235-237, 242-243, 273 
surface normals, 235 
unit normals, 237-238 
OpenGL ES, 1115 
procedural texture mapping, 1083-1084 
beach ball texture, 1091-1096 
checkerboard texture, 1084-1090 
toy ball texture, 1096, 1099-1103 
shadow-compared lighting, 918-925 
specular lighting, 226 
adding, 244-245 
calculating effects of, 228-229 
highlights, 244 
reflectance, 245-246 
specular exponent, 246-248 


specular lighting fragment shaders, 
1077-1083 


specular lighting vertex shaders, 
1021-1032 


spotlights 
creating, 251-252 
drawing, 253-256 
wavelengths, 212 
lightPos[] array, 240, 250 
linear mapping 
eye linear mapping, 452 
object linear mapping, 450-451 
lines 
approximating curves with, 102-104 
drawing 
glBegin/glEnd functions, 100 
line loops, 102 
line stippling, 106-108, 149 
line strips, 102 
line width, 104-106, 150 
sample code listing, 100-102 
normals 
averaging, 248-249 
finding, 238-240 
specifying, 235-237, 242-243, 273 
surface normals, 235 
unit normals, 237-238 
tangent lines, 249 


loops 


LINES program, 101-102 
LINESW program, 105-106 
linking program objects, 985, 1010 
Linux. See GLX 
lists, display. See display lists 
LIT instruction, 950 
LITJET program 
light and rendering context setup, 241 
material properties, 241 
normals and polygons, 242-243 
loading 
compressed textures, 442-443, 468-471 
cube maps, 455-456 
data into buffer objects, 874 
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copying data into buffer objects, 875-876, 


883-884 

mapping buffer objects, 876-881, 888 
feedback buffers, 632-634 
function pointers, 873 
high-level shaders, 982-983, 1011 
identity matrix, 174, 204 
low-level shaders, 946-948, 977 
matrices 

glLoadMatrix function, 188, 205 


glLoadTransposeMatrix function, 189, 


mip levels, 401 
names onto name stack, 614, 636 
textures, 376-379, 427-429 
transformations, 189-192 
LOD_BIAS constant, 404-405 
LOG instruction, 952 
LOGPALETTE structure, 673-674 
lookups 
color lookup tables, 341-344 
copying, 343, 358-359 
parameters, 343, 355-356, 363 
proxies, 343 
replacing, 344, 354, 358 
setting up, 341, 354-355 
dependent lookups, 964, 1058 
loops, 102, 995 
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low-level fragment shaders 
beach ball, 1094-1096 
checkerboard, 1088-1090 
color inversion, 1056 
diffuse lighting, 1074-1077 
grayscale conversion, 1053 
heat signature, 1057 
multiple specular lights, 1079 
per-fragment fog, 1060 
post-process blur, 1063-1064 


procedural texture mapping, 1085-1086 


sepia-tone conversion, 1054 
three lights, 1078-1079, 1081-1083 
toy ball, 1100-1102 
low-level shader extensions, 940-942 
low-level vertex shaders, 945-946 
addresses, 954, 961 
aliases, 954, 960 
attributes, 954 
fragment attributes, 958-959 
vertex attributes, 957-958 
binding, 946, 967 
creating, 946 
deleting, 948, 968 


diffuse lighting low-level shader, 1019-1021 


extension setup, 948-949 
fog application fragment options, 966 


fog coordinate generating low-level shader, 


1032-1037 

input/output modifiers 

input negate, 961 

input swizzle, 961-962 

output clamp, 962-963 

output writemask, 962 
instructions 

ABS, 950 

ADD, 950 

ARL, 952 

CMP, 953 

COS, 953 

DP3, 950 

DpP4, 950 

DPH, 950 


DST, 950 

EX2, 950 

EXP, 952 

FLR, 950 

FRC, 950 

KIL, 953 

LG2, 950 

LIT, 950 

LOG, 952 

LRP, 953 

MAD, 950 

MAX, 951 

MIN, 951 

MOV, 951 

MUL, 951 

POW, 951 

RCP, 951 

RSQ, 951 

SCS, 953 

SGE, 951 

SIN, 953 

SLT, 951 

SUB, 951 

SWZ, 951 

TEX, 953 

TXB, 953 

TXP, 953 

XPD, 951 
loading, 946-948, 977 
names, generating, 946, 969 
native limits, 964-966 
outputs, 954 

fragment outputs, 960 

vertex outputs, 959-960 
parameters 

in-line constants, 954-955 

parameter arrays, 956-957 

program parameters, 955-956 

state-bound constants, 955 
parser limits, 963-964 


point size generating low-level shader, 
1037-1039 


position-invariant vertex option, 966 


precision hint fragment option, 967 
simple low-level shader, 1015, 1018 
specular lighting low-level shader, 1023-1024 


squash-and-stretch low-level shader, 
1040-1043 


temporaries, 954 
texture indirections, 964 


three-colored lights low-level shader, 
1024-1032 


vertex blending low-level shader, 1043-1048 
IProgramLocalParameter4*ARB function, 956 
LRP instruction, 953 
LSTIPPLE program, 107-108 
LSTRIPS program, 103-104 
luminance, 310 
Lunar Lander, 12 


M 


MacOS X, 743 
AGL/Carbon APIs, 744 
bitmap fonts, 760-775 
context management, 747 
double-buffered rendering, 747 
pixel formats, 745-746 
spinning cube sample program, 747-760 
ApplicationServices, 744 
Cocoa API, 744, 775 
NSOpenGL class, 775-778 
spinning cube sample program, 778-787 
GLUT, 744 
OpenGL framework, 744 
MAD instruction, 950 
make command, 796 
Makefile.in file, 795 
mapping 
buffer objects 
glMapBuffer function, 876-877, 888 
object access modes, 877 
sample code listing, 878-881 
cube mapping, 453, 455-457 
eye linear mapping, 452 


matrices 1151 


object linear mapping, 450-451 
pixmaps, 310-311, 361, 825-832 
campfire image example, 312-316 
contexts, 826 
copying, 317, 360-361 
creating, 826 
data types, 311 
drawing, 826 
glXChooseVisual function, 825 
luminance, 310 
moving, 316-317 
packed pixel formats, 311-312 
pixel formats, 310 
reading, 316, 371-372 
saving, 317-320 
sample program, 826-832 
shadow maps 
projecting, 915-918 
regenerating, 911 
sphere mapping, 452-453 
texture mapping. See textures 
masking colors, 292, 298 
matz2 data type, 988 
mat3 data type, 988 
mat4 data type, 988 
material properties, 227, 230-233, 241-242, 272 
matrices 
color matrix, 340-341 
column-major matrix ordering, 186-188 
defined, 166 
GLTMatrix data type, 190 
identity matrix, 172-174, 204 
loading 
glLoadMatrix function, 188, 205 
glLoadTransposeMatrix function, 189, 205 
matrix math, 159-160, 166-167 
matrix stacks, 174-175 
popping matrices off, 178, 207 
pushing matrices onto, 178, 208 
retrieving depth of, 175 
texture matrix stack, 175 
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modelview matrix, 168-171 
multiplication, 192, 206 
row-major matrix ordering, 187 
shadow projection matrix, 261-262 
shadow transformation matrix, 259-260 
specifying, 206 
texture matrix, 382 
MAX instruction, 951 
MCD (Mini-Client Driver), 38-39 
MDC (Mini-Client Driver), 645-646 
memory. See buffers 
MESA, 644 
Mesa library, 797 
messages 
WM_CREATE, 663, 667 
WM_DESTROY, 663 
WM_PAINT, 668-669 
WM_PALETTECHANGED, 671 
WM_QUERYNEWPALETTE, 670 
WM_SIZE, 667 
WM_TIMER, 668 
MFC (Microsoft Foundation Classes), 654 
Microsoft 
Direct3D, 38 
DirectX, 36 
MFC (Microsoft Foundation Classes), 654 
Mini-Client Driver (MCD), 38-39, 645-646 
Windows 95 Game Developers Kit, 36 
migrating to buffer objects, 872-873 
MIN instruction, 951 
Mini-Client Driver (MCD), 38-39, 645-646 
minmax operations, 352, 365-367 
mipmapping, 400-405, 432-433 
hardware generation of mipmaps, 404 
LOD_BIAS, 404-405 
mip levels 
generating, 403-404, 431-433 
hardware generation of mipmaps, 404 
loading, 401 
LOD_BIAS, 404-405 
mipmap filtering, 402-403 
trilinear mipmapping, 403 


mod function, 1090 
modeling quadric surfaces, 483, 485-486 
modeling transformations, 161-162 
MODELIVA program, 589-594 
MODELTEST program, 586-588 
modelview matrix, 168-169 
rotation, 170 
scaling, 171 
transformations, 161-165 
translation, 169 
modes 
display modes 
double-buffer mode, 52 
initializing, 83 
setting, 51 
single-buffer mode, 51 
immediate mode, 25 
polygon modes, 121, 152 
rendering modes 
changing, 616, 637-638 
GL_FEEDBACK, 615, 638 
GL_RENDER, 614-615, 638 
GL_SELECT, 638 
retained mode, 25 
selection mode, 614-615 
monitors 
colors 
CGA (Color Graphics Adapter) cards, 215 
color depth, 217-218 


EGA (Enhanced Graphics Adapter) cards, 
216 


Hercules cards, 215 
producing, 214-215 
Super-VGA cards, 216 
VGA (Video Graphics Array) cards, 216 
resolution, 217 
monopolies, 35 
MOONS program 
rendering code, 621-622 
selection buffer, parsing, 623-624 
Motif library, 839 
callbacks, 841-842 
GLw library functions, 842 


GLwDrawingArea widget, 840-841 
GLwMDrawingArea widget, 840-841 
sample program, 843-855 
application event loop, 844 
callback functions, 844 
code listing, 845-854 
XmForm widget, 843-844 
motion blur, 290-292 
MOTIONBLUR program, 291-292 
mouse 
glutMouseFunc function, 84 
mouse clicks, processing, 615-617 
MOV instruction, 951 
moving pixels, 316-317 
MUL instruction, 951 
multiplying matrices, 192, 206 
multisampling, 283-285 
multitexture, 457-459 
managing, 406-415 
multiple texture coordinates, 459, 471-473 
multitextured sample program, 459-465 
MULTITEXTURE program, 459-465 
multithreaded rendering, 689-690 


N 


name stack 
initializing, 614, 635-636 
loading names onto, 614, 636 
pushing names onto, 614, 637 
removing names from, 637 
naming conventions 
functions, 46, 48 
primitives, 612, 614 
texture objects, 420 
native limits, 964-966 
non-ASCII keystrokes, 86-87 
nonconvex polygons, 129-131 
nonrational numbers, 97 
non-real-time 3D graphics, 23-24 


NURBS (non-uniform rational B-spline) 1153 


non-uniform rational B-splines. See NURBS 
normal vectors. See normals 
normalization, 238 
normals 

averaging, 248-249 

Bézier curves, 500 

finding, 238-240 

quadric surfaces, 480, 540 

specifying, 235-237, 242-243, 273 

surface normals, 235 

unit normals, 237-238 
NSOpenGL class, 775-778 
NSOpenGLPFAAccelerated constant, 776 
NSOpenGLPFAAccumAlphaSize constant, 776 
NSOpenGLPFAAccumBlueSize constant, 776 
NSOpenGLPFAAccumGreenSize constant, 776 
NSOpenGLPFAAccumRedSize constant, 776 
NSOpenGLPFAAIphaSize constant, 776 
NSOpenGLPFAAuxBuffers constant, 776 
NSOpenGLPFABackingStore constant, 776 
NSOpenGLPFABlueSize constant, 776 
NSOpenGLPFABufferSize constant, 776 
NSOpenGLPFAClosestPolicy constant, 776 
NSOpenGLPFADepthSize constant, 776 
NSOpenGLPFADoubleBuffer constant, 776 
NSOpenGLPFAGreenSize constant, 777 
NSOpenGLPFALevel constant, 777 
NSOpenGLPFAMaximumPolicy constant, 777 
NSOpenGLPFAMinimumPolicy constant, 777 
NSOpenGLPFAOffScreen constant, 777 
NSOpenGLPFAPixelSize constant, 777 
NSOpenGLPFARedSize constant, 777 
NSOpenGLPFAStencilSize constant, 777 
NSOpenGLPFAStereo constant, 777 
numbers, nonrational, 97 
numSphereVertices constant, 867 
NURBS (non-uniform rational B-spline), 501-502 

callbacks, 531-532 

creating, 503, 530 

deleting, 503, 526 

error codes, 533 

knots, 502 

NURBS curves, 508, 534 
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piecewise trimming curves, 538-539 
properties, 504, 529, 534-536 
sampling and culling matrices, 530 
surface definition, 504-505, 536-537 
trimming, 505-508, 525, 529 

NV_ extension prefix, 73 


O 


object linear mapping, 450-451 
objects, 159. See also 2D imaging; 3D graphics; 
primitives 

actors 
actor frames, 194-195 
defined, 193 

buffer objects, 865-866 
array indices, 881 
binding to, 874, 882 
checking existence of, 881, 888 
color buffer, 379, 417-418 
copying data into, 875-876, 883-884 
creating, 874 
deleting, 874, 885 
initializing, 874 
listing available buffer names, 874, 885 
mapping, 876-881, 888 
migrating to, 872-873 
pixel rendering buffer, 653 
querying buffer object data stor, 881, 887 
querying pointer to, 881, 886 
querying state of, 881, 885 
rendering with, 874 
state queries, 881 
unmapping, 889 
usage hints, 876 
vertex arrays, 867-872 

foreshortening, 165 

labeling for feedback, 627-630 

program objects 
attaching, 984, 999 
creating, 984 
deleting, 984 


detaching, 984, 1002 
enabling/disabling, 986, 1013 
linking, 985, 1010 
validating, 985-986, 1013 
query objects, 900, 905 
selecting, 630-632 
shader objects, 982-983 
texture objects, 405-406 
vertices, 156 
occluders, 892 
occlusion queries, 891 
bounding boxes, 895-899 
checking results of, 900 
creating, 896, 903 
deleting, 903-904 
ensuring support for, 901-902 
example, 900-901 
marking end of, 897, 904 
occluders, 892 
query objects, 900, 905 
returning unused query object names, 904 
scene without occlusion detection 
final rendering, 893-894 
occluder, 892-893 
verifying names of, 902, 906 
offscreen rendering, 825 
GLX pixmaps, 825-832 
Pbuffers, 832-839 


one-dimensional convolution filters, 347-348, 
356 


OpenGL ES (Open GL for Embedded Systems) 
data types, 1113-1114 
lighting, 1115 
raster operations, 1115 
specification, 1114-1115 
texture mapping, 1115 
OpenGL, future of, 39-40 
OpenGL, history of, 33-34 
API wars, 37 
ARB (Architecture Review Board), 34-35 
Direct3D, 38 
DirectX, 36 
Fahrenheit, 39 


gaming, 37-38 
IRIS GL, 34 


licensing and conformance, 35 
Mini-Client Driver (MCD), 38-39 


PC applications, 36-37 
OpenGL initialization, 52 
OpenGL rendering context 

creating, 663-666 

deleting, 663-667 

initializing, 666-667 

shutting down, 667 
OpenGL Shading Language, 44 
OpenGL State Machine, 97 
OpenGL utility toolkit. See GLUT 
OpenGL.h header file, 45 
opengl32.dll, 44 
OPERATIONS program, 320-327 
operators, 992 
order of curves, 490 
orientations, 480, 540-541 
origin (Cartesian coordinates), 26 


orthographic projections, 30-31, 165-166, 


179-180, 210 
orthonormal, 187 
out qualifier, 990 
output clamp modifier, 962-963 
output writemask modifier, 962 
output/input modifiers 
input negate, 961 
input swizzle, 961-962 
output clamp, 962-963 
output writemask, 962 
outputs, 954 
fragment outputs, 960 
vertex outputs, 959-960 


P 


packed pixel formats, 311-312 


packing pixels into memory, 309-310, 368-369 


PALETTEENTRY structure, 674 
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palettes, 217 

palette arbitration, 670-672 

Windows palettes 
3-3-2 palettes, 674-675 
color index mode, 679 
color matching, 669-670 
creating, 670-678 
destroying, 677-678 
determining need for, 673 


LOGPALETTE structure, 673-674 


message handlers, 671-672 
palette arbitration, 670-672 


PALETTEENTRY structure, 674 


restrictions, 678-679 
PALETTEENTRY structure, 674 
parallelization, 564 
parameters 


color lookup tables, 343, 355-356, 363 


compressed textures, 441-442 
convolutions, 348, 362-363 
histograms, 365 

in-line constants, 954-955 
parameter arrays, 956-957 
program parameters, 955-956 
state-bound constants, 955 


texture parameters, 392, 429-430 
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parametric representation of curves, 488-489 


parser limits, 963-964 
Parsing 
feedback buffers, 632-634 
selection buffers, 623-624 
particles of light, 212-213 
passthrough markers, 627, 636 
Pbuffers, 832-833, 835-839 
contexts, 833 
creating, 833 


framebuffer configuration, 832, 855 


reading, 833 
sample program, 833-839 


1156 per-fragment fog 


per-fragment fog, 1058-1061 
per-vertex procedures. See vertex shaders 
percentage-closer filtering, 919 
performance, measuring, 567-572 
SPHEREWORLD example, 569-572 
stopwatch, 568 
perpendicular lines. See normals 
PERSPECT program, 182-185 
perspective, 13-16 
perspective projections, 31, 165, 180-183 
gluPerspective function, 181, 210 
PERSPECT sample program, 182-185 
SOLAR sample program, 183-185 
PFD_DEPTH_DONTCARE constant, 653 
PFD_DOUBLEBUFFER constant, 653 
PFD_DOUBLE_BUFFER_DONTCARE constant, 653 
PFD_DRAW_TO_BITMAP constant, 653 
PFD_DRAW_TO_WINDOW constant, 653 
PFD_GENERIC_ACCELERATED constant, 653 
PFD_GENERIC_FORMAT constant, 653 
PFD_NEED_PALETTE constant, 653 
PFD_NEED_SYSTEM_PALETTE constant, 653 
PFD_STEREO constant, 653 
PFD_SUPPORT_GDI constant, 653 
PFD_SUPPORT_OPENGL constant, 653 
PFD_SWAP_LAYER_BUFFERS constant, 653 
photo-realistic rendering, 20 
picking, 617-618 
defined, 611 
gluPickMatrix function, 618-620, 639 
hierarchical picking, 620-624 
piecewise curves, 490, 538-539 


pipeline, 43-44, 931-932. See also fragment 
shaders; vertex shaders 


fixed fragment processing, 935-936 
fixed functionality, 931, 938-939 
fixed vertex processing 

clipping, 934-935 

lighting, 932-934 

texture coordinate processing, 934 

vertex transformations, 932 


imaging pipeline 
color lookup tables, 341-344, 354-356, 
358-359, 363 
color matrix, 340-341 
convolutions, 344-348, 356-357, 362-363 
histograms, 349-352, 364-367 
states 
buffer object state queries, 879 
checking status of, 68, 79 
disabling, 68, 75-76 
enabling, 68, 75-76 
quadric states, 478-480 
restoring, 69 
saving, 69 
sorting, 285 
state machine, 68 
texture states, 376 
transformation pipline, 167-168 
pitch, 195 
pixel buffers. See color buffers 
PIXELFORMATDESCRIPTOR structure, 651, 653 
pixels, 90 
AGL/Carbon pixel formats, 745-746 
campfire image example, 312-316 
gltLoadTGA function, 314-316 
RenderScene function, 312-313 
copying, 317, 360-361 
data types, 311, 378 
luminance, 310 
mapping, 333-334, 368 
moving, 316-317 
OPERATIONS sample program, 320-327 
pixel formats, 310, 650-651 
describing, 651-653 
enumerating, 654-655, 726-729 
extended pixel formats, 694-696 
pixel rendering buffer, 653 
returning, 729 
selecting, 656-657, 725-726 
setting, 656-657, 729-730 
pixel packing, 309-312, 368-369 
pixel transfer, 329-333, 369-370 
pixel zoom, 327-328, 370 


pixmaps, 310-311, 361, 825-832 
campfire image example, 312-316 
contexts, 826 
copying, 317, 360-361 
creating, 826 
data types, 311 
drawing, 826 
glXChooseVisual function, 825 
luminance, 310 
moving, 316-317 
packed pixel formats, 311-312 
pixel formats, 310 
reading, 316, 371-372 
sample program, 826-832 
saving, 317-320 

reading, 316, 371-372 

saving, 317-320 

pixmaps, 310-311, 361, 825-832 

campfire image example, 312-316 

contexts, 826 

copying, 317, 360-361 

creating, 826 

data types, 311 

drawing, 826 

glXChooseVisual function, 825 

luminance, 310 

moving, 316-317 

packed pixel formats, 311-312 

pixel formats, 310 

reading, 316, 371-372 

sample program, 826-832 

saving, 317-320 

planar polygons, 128 
planes, 26 
PLANETS program 

primitives, naming, 613-614 

selection buffer, 616-617 

selection mode, 615 

platform independence, 48-49 
pointers 

Display, 798 

function pointers, 873 


polygons 


vertex arrays, 580-581, 610 
XVisuallnfo, 799 
points 

drawing, 93-94, 156 
glBegin function, 93 
glEnd function, 93 
point size, 97-100, 151 
sample code listing, 94-95 


point size generating vertex shaders, 
1037-1039 


POINTS program, 94-95 
POINTSZ program, 98-99 
polygons 
buffers 
buffer targets, 132-134 
depth buffers, 134-135 
stencil buffers, 136-156 
convex polygons, 128 
edges, 129-131, 147 
general polygons, 123 
nonconvex polygons, 129-131 
offset, 926, 930 
planar polygons, 128 
polygon construction rules, 128-129 
polygon modes, 121, 152 
polygon offset, 926, 930 
quadrilaterals, 122-123 
scissor box, 135-136, 154 
solid objects, 112 
colors, 116 
culling, 118-121, 144 
hidden surface removal, 116-118 
RenderScene function, 113-116 
SetupRC function, 113-116 
stippling, 123-127, 153 
subdivision, 129-131 
triangles 
glBegin/glEnd functions, 109 
sample code listing, 113-116 
triangle fans, 112 
triangle strips, 111 
winding, 110-111 
winding, 237 
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Pong, 12 
popping matrices from matrix stack, 178, 207 
position-invariant vertex option, 966 


post-process blur high-level fragment shader, 
1062 


post-process blur low-level fragment shader, 
1063-1064 


POW instruction, 951 
precision hint fragment option, 967 
prefixes (extensions), 73-74 
preprocessed batches, 564-566 
primitives, drawing, 89-90 
3D canvases, 90-91 
buffers 
buffer targets, 132-134 
depth buffers, 134-135 
stencil buffers, 136-156 
convex polygons, 128 
curves, 102-104 
edges, 129-131, 147 
general polygons, 123 
lines 
approximating curves with, 102-104 
glBegin/glEnd functions, 100 
line loops, 102 
line stippling, 106-108, 149 
line strips, 102 
line width, 104-106, 150 
sample code listing, 100-102 
names 612-614 
nonconvex polygons, 129-131 
pixels, 90 
planar polygons, 128 
points, 93-94 
glBegin function, 93 
glEnd function, 93 
point size, 97-100, 151 
sample code listing, 94-95 
polygon construction rules, 128-129 
quadrilaterals, 122-123 
scissor box, 135-136, 154 


solid objects, 112 
colors, 116 
culling, 118-121, 144 
hidden surface removal, 116-118 
polygon modes, 121, 152 
RenderScene function, 113-116 
SetupRC function, 113-116 
stippling, 123-127, 153 
subdivision, 129-131 
triangles 
glBegin/glEnd functions, 109 
sample code listing, 113-116 


triangle fans, 112 
triangle strips, 111 
winding, 110-111 
vertices, 92-93, 156 
priorities, 416, 424 
procedural texture mapping, 1083-1084 
beach ball texture, 1091-1096 
checkerboard texture, 1084-1090 
high-level fragment shader, 1084 
low-level fragment shader, 1085-1086 
toy ball texture, 1096, 1099-1103 
ProcessPlanet function, 619, 623 
ProcessSelection function, 623, 630 
program objects. See also programs 
attaching, 984, 999 
creating, 984 
deleting, 984 
detaching, 984, 1002 
enabling/disabling, 986, 1013 
linking, 985, 1010 
validating, 985-986, 1013 
program parameters, 955-956 


programmable fragment shaders. See fragment 
shaders 


programmable vertex shaders. See vertex 
shaders 


programming environment, 49 
programs. See also program objects; shaders 
AGL/Carbon spinning cube program 
bitmap fonts, 760-775 
initial code listing, 747-760 


Cocoa spinning cube program, 778-787 
GLX pixmap program, 826-832 
Motif program, 843-855 
application event loop, 844 
callback functions, 844 
code listing, 845-854 
XmForm widget, 843-844 
Pbuffer program, 833-839 
Xlib spinning cube program 
bitmap fonts, 812-824 
initial code listing, 801-812 
ATOM 
glPopMatrix function, 178 
glPushMatrix function, 178 
glRotatef function, 178 
glTranslatef function, 178 
RenderScene function, 175-177 
BEZ3D, 496-499 
BEZIER, 491-494 
BITMAPS, 303, 305-307 
CCUBE, 
drawing colors, 220-221 
flat shading, 223 
shading, 221-223 
CUBEDX, 582-585 
CUBEMAP, 455-456 
FLORIDA, 512-514 
GLRECT 
clipping volumes, 58-62, 79-80 
device contexts, 661-663 
OpenGL rendering context, 663-667 
rectangles, 57-58, 81 
screen, Clearing, 55-56 
viewports, 58-59, 81-82 
windows, 58, 85, 658-661 
WM_PAINT message, 668-669 
WM_SIZE message, 667 
WM_TIMER message, 668 
GLView, 654 
IMAGELOAD, 312-316 
gltLoadTGA function, 314-316 
RenderScene function, 312-313 
IMAGING, 336-339 
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LINES, 101-102 

LINESW, 105-106 

LITJET 
light and rendering context setup, 241 
material properties, 241 
normals and polygons, 242-243 

LSTIPPLE, 107-108 

LSTRIPS, 103-104 

MODELIVA, 589-594 

MODELTEST, 586-588 

MOONS 
rendering code, 621-622 
selection buffer, parsing, 623-624 

MOTIONBLUR, 291-292 

MULTITEXTURE program, 459-465 

OPERATIONS, 320-327 

PERSPECT, 182-185 

PLANETS 
primitives, naming, 613-614 
selection buffer, 616-617 
selection mode, 615 

POINTS, 94-95 

POINTSZ, 98-99 

PSTIPPLE, 126-127 

PYRAMID, 383-390 

REFLECTION, 278-279 

SELECT 
feedback buffer, 632-634 
rendering code, 627-629 
selection processing, 630-632 

SHINYHET, 247-248 

SIMPLE 
body, 51 
code listing, 49-51 
color buffer, clearing, 53-54, 75 
display callback function, 52, 82-83 
display mode, 51-52 
GLUT main loop, 52, 84 
header, 51 
OpenGL initialization, 52 
OpenGL window, 52, 82 
queue, flushing, 54-55, 77 
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SINGLE, 133-134 

SNOWMAN, 483-486 

SOLAR, 183-185 

SPHEREWORLD, 196-203, 264, 569-572 
code listing, 197-199 
DrawGround function, 200-201 
glPopMatrix function, 201-202 
glPushMatrix function, 201-202 
gltApplyActorTransform function, 201 
gltApplyCameraTransform function, 201 
gitInitFrame function, 200 
gltMoveFrameForward function, 202 
gltRotateFrameLocalY function, 202 
SetupRC function, 200 
SpecialKeys function, 202-203 

SPHEREWORLD32, 696-724 

SPOT 
lighting setup, 251-252 
RenderScene function, 254-255 

STAR, 130-131 

STARFIELD, 575-578 

STENCIL, 139-140 

TEXGEN, 444-450 

TEXT3D, 679-681 

TOON, 396-400 

TRANSFORM, 189-192 

TRIANGLE, 113-116 

TUNNEL, 407-415 

WINRECT, 648-649 

projections, 30, 160, 165-166, 178-179 
defined, 161 
orthographic projections, 30-31, 165-166, 
179-180, 210 

perspective projections, 31, 165, 180-183 
gluPerspective function, 181, 210 
PERSPECT sample program, 182-185 
SOLAR sample program, 183-185 

shadow maps, 915-918 

shadow projection matrix, 261-262 

viewing projections, 209 


properties 
material properties, 227, 230-233, 241-242, 
272 
NURBS, 504, 529, 534-536 
tessellators, 545 
PSTIPPLE program, 126-127 
pushing 
items onto attribute stack, 69, 80 
matrices onto matrix stack, 178, 208 
names onto name stack, 614, 637 
PYRAMID program, 383-390 


Q 


quadratic curves, 490 
quadric states, 478-480 
quadric surfaces 
callbacks, 539 
cylinders, 481, 525-526 
disks, 483, 527-528 
draw styles, 479, 539-540 
drawing, 480, 483 
modeling with, 483-486 
normals, 480, 540 
orientation, 480, 540-541 
quadric states, 478-480 
snowman model example, 483-486 
spheres, 480-481, 541-542 
texture coordinates, 480, 541 
quadrilaterals, 122-123 
Quake, 37 
qualifiers, 990 
quaternions, 195 
queries 
buffer object state, 881, 885 
occlusion queries, 891 
bounding boxes, 895-899 
checking results of, 900 
creating, 896, 903 
deleting, 903-904 
ensuring support for, 901-902 
example, 900-901 


marking end of, 897, 904 

occluders, 892 

query objects, 900, 905 

returning unused query object names, 904 


scene without occlusion detection, 
892-894 


verifying names of, 902, 906 
querying properties of, 905 
queue, flushing, 54-55, 77 


R 


raster operations, 1115 
raster position, 307-308, 370-371, 374 
RCP instruction, 951 
reading 
Pbuffers, 833 
pixels, 316, 371-372 
stopwatch, 568 
real-time 3D graphics, 12, 21-24 
RealizePalette function, 671 
reflection 
REFLECTION program, 278-279 
specular reflectance, 245-246 
RegenerateShadowMap function, 911 
regenerating shadow maps, 911 
ReleaseDC function, 661-662 
removing. See deleting 
RenderHead function, 550, 553-554 
rendering. See also drawing; pipeline 
bolt model 
breaking into parts, 548-549 
head, 549-554 
model assembly, 561-562 
shaft, 554-557 
threads, 557-561 
buffer objects, 874 
defined, 15 
display lists 
batch processing, 563-564 
converting to, 566-567 
creating, 565, 602-603, 607-608 
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deleting, 565, 599 

display list caveats, 566 
executing, 566, 597 

executing array of, 566, 597-598 
preprocessed batches, 564-566 


ranges of empty display lists, generating, 
565, 603-604 


testing existance of, 605 
double-buffered rendering, 747 
DRI (Direct Rendering Infrastructure), 796 
full-screen rendering 
frameless windows, 685-686 
full-screen windows, 686-689 
GLX 
GLX pixmaps, 825-832 
Pbuffers, 832-839 
immediate mode, 25 
light viewpoint, 909-913 
modes 
changing, 616, 637-638 
GL_FEEDBACK, 615, 638 
GL_RENDER, 614-615, 638 
GL_SELECT, 638 
multithreaded rendering, 689-690 
occlusion queries, 891 
bounding boxes, 895-899 
checking results of, 900 
creating, 896, 903 
deleting, 903-904 
ensuring support for, 901-902 
example, 900-901 
marking end of, 897, 904 
occluders, 892 
query objects, 900, 905 
returning unused query object names, 904 
scene without occlusion detection, 
892-894 
verifying names of, 902, 906 
performance, measuring, 567-572 
SPHEREWORLD example, 569-572 
stopwatch, 568 
photo-realistic rendering, 20 
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rendering context, 657-658 
copying, 732 
creating, 658, 663-666, 731 
current context, returning, 736 
deleting, 663-667, 732 
initializing, 666-667 
making current, 658, 737 
shutting down, 667 

retained mode, 25 

scissor box, 135-136, 154 

shadows, 262-264 


switching between antialiasing and normal 
rendering, 282-283 


vertex arrays, 574 

data types, 580 

enabling, 579 

geometry, loading, 578-579 

indexed vertex arrays, 582, 585-596 

pointers, 580-581, 610 

rendering functions, 581-582 

sizes, 580 

STARFIELD sample program, 575-578 
Windows rendering. See Windows 


RenderOnce function, 692 
RenderScene function, 52, 312-313, 619, 629 


ATOM program, 175-177 
BEZIER program, 494-495 
bolt model, 562 

IMAGING program, 336-339 
PYRAMID program, 390 
REFLECTION program, 278 
SPOT program, 254-255 
TRIANGLE program, 113-116 


restoring states, 69 
retained mode, 25 
retina, 214 
returning pixel formats, 729 
RGB colorspace, 218, 220 
roll, 195 
rotation 
glRotate function, 208 
glRotatef function, 170 
modelview matrix, 170 
row-major matrix ordering, 187 
RSQ instruction, 951 


S 


sampler1D data type, 988 
sampler1DShadow data type, 988 
sampler2D data type, 988 
sampler2DShadow data type, 988 
sampler3D data type, 988 
samplerCube data type, 988 
saving 
pixels, 317-320 
states, 69 
scalars, 167 
scaling 
glScale function, 208 
glScalef function, 171 
modelview matrix, 171 
windows, 58, 85 
scene graphs, 25 
scenes, fitting to window, 909 
scintillation, 400 


RenderShaft function, 555-557 
RenderThread function, 558-561 
replacing color lookup tables, 344, 354, 358 
resetting stopwatch, 568 
resident textures, 415-417 
resolution, 217 
resource consumption 
native limits, 964-966 
parser limits, 963-964 
texture indirections, 964 


scissor box, 135-136, 154 

screens. See monitors 

SCS instruction, 953 

searching for extensions, 72-73 

secondary color, 435-437, 473-474 

SELECT program 
feedback buffer, 632-634 
rendering code, 627-629 
selection processing, 630-632 


selection, 612 
defined, 611 
object selection, 630-632 
picking, 617-618 
gluPickMatrix function, 618-620, 639 
hierarchical picking, 620-624 
selection buffers, 615-617, 638 
selection mode, 614-615 
separable convolution filters, 346-347, 373 
sepia tone conversion, 1053-1055 
servers, X servers, 798 
SetDCPixelFormat function, 664 
SetPixelFormat function, 656-657, 664, 729-730 
SetTimer function, 668 
SetupRC function, 52, 200, 229, 240, 325, 389 
fog effect, 286 
TRIANGLE program, 113-116 
SGE instruction, 951 
SGI_ extension prefix, 73 
shader objects, 982-983 
shaders. See fragment shaders; vertex shaders 
shading, 16 
flat shading, 223 
glColor function, 221-223 
shading models, selecting, 223, 274 
smooth shading, 221-223 
shadows, 17, 258, 907-908 
alpha test function, 928 
ambient lighting, 913-914 
defined, 258-259 
depth textures, 913, 919 
diffuse lighting, 914 
drawing, 913-914 
eye linear texture coordinate generation, 917 
GL_ARB_shadow_ambient extension, 925-926 
hidden surface removal, 918 
light viewpoint, 908-913 
percentage-closer filtering, 919 
polygon offset, 926, 930 
rendering, 262-264 
sample code listing, 920-925 
scenes, fitting to window, 909 
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shadow comparison, 918-920 
shadow maps 
projecting, 915-918 
regenerating, 911 
shadow projection matrix, 261-262 
shadow transformation matrix, 259-260 
texture coordinates, 918 
shaft of bolt model, 554-557 
shapes, drawing, 90. See also surfaces 
3D canvases, 90-91 
bouncing square animation, 63-66 
buffers 
buffer targets, 132-134 
depth buffers, 134-135 
stencil buffers, 136-140, 143, 154-156 
convex polygons, 128, 515-518 
cubes, 169 
curves, 102-104 
cylinders, 481, 525-526 
disks, 483, 527-528 
frustrums, 181, 204 
general polygons, 123 
lines 
approximating curves with, 102-104 
glBegin/glEnd functions, 100 
line loops, 102 
line stippling, 106-108, 149 
line strips, 102 
line width, 104-106, 150 
sample code listing, 100-102 
nonconvex polygons, 129-131 
pixels, 90 
planar polygons, 128 
points 
glBegin function, 93 
glEnd function, 93 
point size, 97-100, 151 
sample code listing, 94-95 
polygon construction rules, 128-129 
polygon offset, 926, 930 
polygon winding, 237 
quadrilaterals, 122-123 
rectangles, 57-58, 81 
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scissor box, 135-136, 154 
solid objects, 112 
colors, 116 
culling, 118-121, 144 
hidden surface removal, 116-118 
polygon modes, 121, 152 
RenderScene function, 113-116 
SetupRC function, 113-116 
spheres, 480-481, 541-542 
stippling, 123-127, 153 
subdivision, 129-131, 147 
tessellation, 508-510 
callbacks, 510-512, 543-544 
convex polygons, 515-516 


convex polygons with multiple contours, 
516-518 


creating, 531 
deleting, 527 
properties, 545 
sample program, 512-514 
vertex data, 512, 546 
torus, 189 
triangles 
glBegin/glEnd functions, 109 
sample code listing, 113-116 
triangle fans, 112 
triangle strips, 111 
winding, 110-111 
vertices, 92-93 
sharpen, 1065-1067 
SHINYJET program, 247-248 
shutting down rendering context, 667 
SigGraph conference, 38 
Silicon Graphics IRIS GL, 34 
simple extensions, 691-692 
SIMPLE program 
body, 51 
code listing, 49-51 
color buffer, clearing, 53-54, 75 
display callback function, setting, 52, 82-83 
display mode, 51-52 
GLUT main loop, running, 52, 84 
header, 51 


OpenGL initialization, 52 
OpenGL window, creating, 52, 82 
queue, flushing, 54-55, 77 
sin function, 97 
SIN instruction, 953 
SINGLE program, 133-134 
single-buffered mode, 51 
sizing 
points, 97-100, 151 
vertex arrays, 580 
SLT instruction, 951 
smooth shading, 221-223 
smoothstep function, 1096 
snowman model, 483-486 
SOLAR program, 183-185 
solid objects, drawing, 112 
colors, 116 
culling, 118-121, 144 
hidden surface removal, 116-118 
polygon modes, 121, 152 
RenderScene function, 113-116 
SetupRC function, 113-116 
sorting state, 285 
source colors, 276 
SpecialKeys function, 202-203 
specref[] array, 246 
specular exponent, 246-248 
specular lighting, 226 
adding, 244-245 
calculating effects of, 228-229 
highlights, 244 
multiple specular lights, 1077-1083 
reflectance, 245-246 
specular exponent, 246-248 
specular lighting vertex shaders 
specular lighting high-level shader, 
1021-1022 
specular lighting low-level shader, 
1023-1024 


three-colored lights high-level shader, 


1024-1026, 1029 


three-colored lights low-level shader, 
1024-1032 


specular reflectance, 245-246 
specular[] array, 245 
spheres 
drawing, 480-481, 541-542 
mapping, 452-453 
particle cloud spheres, 867-868 
sphere vertex array, 868-872 
SPHEREWORLD program, 196-203, 264, 569-572 
code listing, 197-199 
DrawGround function, 200-201 
glPopMatrix function, 201-202 
glPushMatrix function, 201-202 
gltApplyActorTransform function, 201 
gltApplyCameraTransform function, 201 
gltInitFrame function, 200 
gltMoveFrameForward function, 202 
gltRotateFrameLocalY function, 202 
SetupRC function, 200 
SpecialKeys function, 202-203 
SPHEREWORLD32 program, 696-724 
spinning cube program 
AGL/Carbon 
bitmap fonts, 760-775 
initial code listing, 747-760 
Cocoa, 778-787 
Xlib 
bitmap fonts, 812-824 
initial code listing, 801-812 
SPOT program 
lighting setup, 251-252 
RenderScene function, 254-255 
spotlights 
creating, 251-252 
drawing, 253-256 
spring-shaped path of points, drawing, 94-95 
squash-and-stretch vertex shaders, 1040-1043 
stacks 
attribute stack, 69, 80 
matrix stacks, 174-175 
popping matrices off, 178, 207 
pushing matrices onto, 178, 208 


strstr function 


retrieving depth of, 175 
texture matrix stack, 175 
name stack 
initializing, 614, 635-636 
loading names onto, 614, 636 
pushing names onto, 614, 637 
removing names from, 637 
STAR program, 130-131 
STARFIELD program, 575-578 
state-bound constants, 955 
state machine, 68, 97 
statements 
discard, 996 
if/else, 995-996 
loops, 995 
states 
buffer object state queries, 881 
checking status of, 68, 79 
disabling, 68, 75-76 
enabling, 68, 75-76 
quadric states, 478-480 
restoring, 69 
saving, 69 
sorting, 285 
state machine, 68 
texture states, 376 
stencil buffers 
glClearStencil function, 143 
glStencilFunc function, 136-138, 154-155 
glStencilMask function, 140, 155 
glStencilOp function, 138-140, 155-156 
STENCIL program, 139-140 
step function, 1090 
stippling, 106-108, 123-127, 149, 153 
stopwatch, 568 
strips 
lines, 102 
quad, 123 
triangles, 111 
strstr function, 72 
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structures, 988-989 
GLYPHMETRICSFLOAT, 681 
LOGPALETTE, 673-674 
PALETTEENTRY, 674 
PIXELFORMATDESCRIPTOR, 651-653 

SUB instruction, 951 

subdivision (polygons), 129-131 

Summit, 797 

Sun/Earth/Moon system, 183-185 

Super-VGA cards, 216 

surfaces, 477 
Bézier curves, 487-488 

2D curves, 491-495 

3D curves, 496-499 

breakpoints, 490 

continuity, 490 

control points, 489-490 

cubic curves, 490 

degree, 490 

evaluating, 496 

evaluators, 491, 521-523 

lighting, 500 

mapping grids, 496, 523-524 

normals, 500 

order, 490 

parametric representation, 488-489 

piecewise curves, 490 

quadratic curves, 490 
culling, 118-121, 144 


hidden surface removal, 16, 116-118, 918 


NURBS, 501-502 
callbacks, 531-532 
creating, 503, 530 
deleting, 503, 526 
error codes, 533 
knots, 502 
NURBS curves, 508, 534 
piecewise trimming curves, 538-539 
properties, 504, 529, 534-536 
sampling and culling matrices, 530 
surface definition, 504-505, 536-537 
trimming, 505-508, 525, 529 


quadric surfaces 

callbacks, 539 

cylinders, 481, 525-526 

disks, 483, 527-528 

draw styles, 479, 539-540 

drawing, 480, 483 

modeling with, 483, 485-486 

normals, 480, 540 

orientation, 480, 540-541 

quadric states, 478-480 

snowman model example, 483-486 

spheres, 480-481, 541-542 

texture coordinates, 480, 541 
surface normals 

converting to unit normals, 237-238 

defined, 235 

specifying, 235-237, 242-243, 273 
tessellation, 508-510 

callbacks, 510-512, 543-544 


convex polygons with multiple contours, 
$16-518 


convex polygons, drawing, 515-516 
creating, 531 
deleting, 527 
properties, 545 
sample program, 512-514 
vertex data, 512, 546 
SwapBuffers function, 669, 730 
SWZ instruction, 951 


T 


tables, color lookup tables 
parameters, 363 
setting up, 341, 354-355 
tangent lines, 249 
targets, buffer targets, 132-134 
temporaries, 954 
tessellation, 256, 508-510 
callbacks, 510-512, 543-544 


convex polygons with multiple contours, 
$16-518 


convex polygons, drawing, 515-516 


creating, 531 
deleting, 527 
properties, 545 
sample program, 512-514 
vertex data, 512, 546 
testing, 293-294 
TEX instruction, 953 
texel formats, 18, 377-378, 913 
TEXGEN program, 444-450 
text 
fonts, 679 
2D fonts, 682-684, 739 
3D fonts, 679-681, 739-741 
3D text rendering, 681 
APL/Carbon APIs, 760-775 
GLX, 812-824 
shader text, 982-983, 1011 
TEXT3D program, 679-681 
texture environment mode, 390-392, 426-427 
texture indirections, 964 
texture matrix stack, 175 
textures, 375, 435 
active texture, setting, 467-468 
allocating, 405 
anisotropic filtering, 403, 438-440 
applying, 935 
beach ball texture, 1091-1096 
binding, 405, 417 
checkerboard texture, 1084-1090 
compressed textures, 440-441 
compressed texture formats, 441-442 
loading, 442-443, 468-471 
parameters, 441-442 
copying from color buffer, 379, 417-418 
cube mapping, 453-457 
deleting, 405, 419-420 
dependency texture lookups, 1058 
depth textures, 913, 919 
eye linear mapping, 452 
filtering, 392-393 
internal formats, 377 
loading, 376-379, 427-429 
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mipmapping, 400-405, 432-433 
hardware generation of mipmaps, 404 
LOD_BIAS, 404-405 
mip levels, 403-404, 431-433 
mipmap filtering, 402-403 
trilinear mipmapping, 403 

multitexture, 457-459 
managing, 406-415 
multiple texture coordinates, 459, 471-473 
multitextured sample program, 459-465 

names, generating, 420 

object linear mapping, 450-451 

OpenGL ES, 1115 

parameters, 392, 420-422, 429-430 

pixel data types, 378 

priorities, 416, 424 

procedural texture mapping, 1083-1084 

quadric surfaces, 480, 541 

resident textures, 415-417 

returning, 423 

secondary color, 435-437, 473-474 

simple 2D example, 383-390 

sphere mapping, 452-453 © 

texel formats, 377-378 

texture combiners, 465-467 


texture coordinate generation, 443-450, 
474-475 


texture coordinates, 380-382, 424-426, 918, 
934 


texture environment mode, 390-392, 426-427 
texture indirections, 964 

texture lookups, 939-940, 998-999 

texture matrix, 382 

texture objects, 405-406 

texture states, 376 

texture wrap, 394-395 


toon-shading (cartoons with texture), 
395-400 


toy ball texture, 1096-1103 
updating, 379-380, 418-419 
verifying, 423-424 


threads of bolt model, 557-561 
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three lights shaders 


high-level fragment shader, 1077-1078, 
1080-1081 


high-level vertex shader, 1024-1026, 1029 


low-level fragment shader, 1078-1079, 
1081-1083 


low-level vertex shader, 1024-1032 
three-dimensional graphics. See 3D graphics 
TimerFunction function, 64 
TOON program, 396-400 
toon-shading (cartoons with texture), 395-400 
torus, 189 
toy ball 

high-level fragment shader, 1098-1100 

low-level fragment shader, 1100-1102 

procedural texture, 1096-1103 
tracking color, 231 
transferring pixels, 329-333, 369-370 
TRANSFORM program, 189-192 
transformation pipline, 167-168 
transformations, 159 

actor frames, 194-195 

adding together, 192-193 

ATOM program example 

glPopMatrix function, 178 
glPushMatrix function, 178 
glRotatef function, 178 
glTranslatef function, 178 
RenderScene function, 175-177 

camera management, 196 

column-major matrix ordering, 186-188 

creating and loading, 189-192 

Euler angles, 195 

eye coordinates, 161 

hardware T&L (transform and lighting), 188 

identity matrix, 172-174, 204 

matrix loading 

glLoadMatrix function, 188, 205 
glLoadTransposeMatrix function, 189, 205 
matrix math, 159-160, 166-167 
matrix multiplication, 192, 206 


matrix stacks, 174-175 
popping matrices off, 178, 207 
pushing matrices onto, 178, 208 
retrieving depth of, 175 
texture matrix stack, 175 
modeling transformations, 161-162 
modelview matrix, 163-165, 168-171 
defined, 161 
rotation, 170 
scaling, 171 
translation, 169 
projections, 165-166, 178-179 
defined, 161 


orthographic projections, 165-166, 
179-180 
perspective projections, 165, 180-183 
rotation 
glRotate function, 208 
glRotatef function, 170 
modelview matrix, 170 
row-major matrix ordering, 187 
scaling 
glScale function, 208 
glScalef function, 171 
modelview matrix, 171 
shadow transformation matrix, 259-260 
SPHEREWORLD sample program, 196-203 
code listing, 197-199 
DrawGround function, 200-201 
glPopMatrix function, 201-202 
glPushMatrix function, 201-202 
gltApplyActorTransform function, 201 
gltApplyCameraTransform function, 201 
gitInitFrame function, 200 
gltMoveFrameForward function, 202 
gltRotateFrameLocalY function, 202 
SetupRC function, 200 
SpecialKeys function, 202-203 
squash-and-stretch vertex shaders, 1040-1043 
TRANSFORM program, 189-192 
transformation pipline, 167-168 


translation 
giTranslate function, 209 
glTranslatef function, 169 
modelview matrix, 169 
vertices, 932 
viewing transformations, 161-162, 166 
translation 
glTranslate function, 209 
giTranslatef function, 169 
modelview matrix, 169 
transparency, 19 
TRIANGLE program, 113-116 
triangles 
drawing, 109 
sample code listing, 113-116 
triangle fans, 112 
triangle strips, 111 
winding, 110-111 
trigonometry, 96 
trilinear mipmapping, 403 
trimming NURBS surfaces, 505-508, 525, 529 
true color mode, 218 
TrueType fonts, 679 
2D fonts, 682-684, 739 
3D fonts, 679-681, 739-741 
3D text rendering, 681 
TUNNEL program, 407-415 
turning on. See enabling 


two-dimensional convolution filters, 345, 
356-357 


two-dimensional graphics. See 2D imaging 
TXB instruction, 953 
TXP instruction, 953 


types. See data types 


U-V 

uniform qualifier, 990 

unit normals, 237-238 

unmapping buffer objects, 878, 889 
updating textures, 379-380, 418-419 
usage hints, 876 
UserMultiPassTechnique function, 692 
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ValidateRect function, 669 
validating program objects, 985-986, 1013 
variables 
addresses, 954, 961 
aliases, 954, 960 
arrays, 989-992 
attributes, 954 
fragment attributes, 958-959 
vertex attributes, 957-958 
built-in variables, 990-991 
data types, 988 
environment variables, DISPLAY, 798 
outputs, 954 
fragment outputs, 960 
vertex outputs, 959-960 
parameters 
in-line constants, 954-955 
parameter arrays, 956-957 
program parameters, 955-956 
state-bound constants, 955 
qualifiers, 990 
structures, 988-989 
temporaries, 954 
varying qualifier, 990 
vec2 data type, 988 
vec3 data type, 988 
vec4 data type, 988 
vectors. See normals 
verifying texture names, 423-424 
versions, checking, 71, 78 
vertex arrays, 574, 867 
data types, 580 
enabling, 579, 869 
geometry, loading, 578-579 
indexed vertex arrays 
creating, 589-594 
glDrawElements function, 585, 600 


glDrawRangeElements function, 586, 
600-601 


glinterleavedArrays function, 586, 604-605 
glMultiDrawArrays function, 586 
memory requirements, 588-589, 595-596 
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MODELTEST sample program, 586-588 
simple cube example, 582-585 
pointers, 580-581, 610 
rendering, 581-582 
sizes, 580 
sphere vertex array, 869-872 
spherical particle clouds, 867-868 
STARFIELD sample program, 575-578 
vertex outputs, 959-960 
vertex shaders, 1015 
high-level shaders, 981-982 
array access, 992 
arrays, 989-990 
built-in variables, 990-991 
compiling, 983-984, 1000 
component selectors, 994 
constructors, 992-994 
creating, 982, 1001 
data types, 988 
deleting, 982, 1002 


diffuse lighting high-level shader, 
1018-1019 


discard statement, 996 
extension setup, 986-987 


fog coordinate generating high-level 
shader, 1032, 1034 


functions, 996-999 

if/else statements, 995-996 

loops, 995 

operators, 992 

point size generating high-level shader, 
1037-1039 

program objects, 984-986, 1013 

qualifiers, 990 

shader text, 982-983, 1011 

simple high-level shader, 1015-1018 

specular lighting high-level shader, 
1021-1022 

squash-and-stretch high-level shader, 
1040-1043 

structures, 988-989 


three-colored lights high-level shader, 
1024-1026, 1029 

vertex blending high-level shader, 
1043-1048 


low-level shaders, 945-946 


addresses, 954, 961 
aliases, 954, 960 
attributes, 954, 957-959 
binding, 946, 967 
creating, 946 

deleting, 948, 968 


diffuse lighting low-level shader, 
1019-1021 


extension setup, 948-949 
fog application fragment options, 966 


fog coordinate generating low-level 
shader, 1032-1037 


input/output modifiers, 961-963 
instructions, 950-953 

loading, 946-948, 977 

names, generating, 946, 969 
native limits, 964-966 

outputs, 954, 959-960 
parameters, 954-957 

parser limits, 963-964 


point size generating low-level shader, 
1037-1039 


position-invariant vertex option, 966 
precision hint fragment option, 967 
simple low-level shader, 1015, 1018 


specular lighting low-level shader, 
1023-1024 


squash-and-stretch low-level shader, 
1040-1043 


temporaries, 954 

texture indirections, 964 

three-colored lights low-level shader, 
1024-1032 

vertex blending low-level shader, 
1043-1048 


vertex-specific instruction set, 952 
vertices, 29. See also vertex shaders 
blending, 1043-1048 
drawing, 92-93, 156 
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fixed vertex processing 
clipping, 934-935 
lighting, 932-934 
texture coordinate processing, 934 
vertex transformations, 932 
transformations, 932, 1040-1043 
vertex arrays, 574, 867 
data types, 580 
enabling, 579, 869 
geometry, loading, 578-579 
indexed vertex arrays, 582-596 
pointers, 580-581, 610 
rendering, 581-582 
sizes, 580 
sphere vertex array, 869-872 
spherical particle clouds, 867-868 
STARFIELD sample program, 575-578 
vertex shaders, 1015 
VGA (Video Graphics Array) cards, 216 
video memory. See buffers 
viewing projections gluLookAt function, 209 
viewing transformations defined, 161-162 
viewport transformations, 166 
defined, 161 
viewports, 27-29 
defining, 58-59, 81-82 
visual attribute list constants (GLX), 798-800 
void data type, 988 


Ww 


wavelengths, 212 
WGL extensions, 693-694 

accessing, 693 

extended pixel formats, 694-696 
WGL_ extension prefix, 73 
WGL_ACCELERATION_ARB constant, 694 
WGL_ACCUM_ALPHA_BITS_ARB constant, 695 
WGL_ACCUM_BITS_ARB constant, 695 
WGL_ACCUM_BLUE_BITS_ARB constant, 695 
WGL_ACCUM_GREEN_BITS_ARB constant, 695 


WGL_ACCUM_RED _BITS_ARB constant, 695 
WGL_ALPHA_BITS_ARB constant, 695 
WGL_ALPHA_SHIFT_ARB constant, 695 
WGL_AUX_BUFFERS_ARB constant, 695 
WGL_BLUE_BITS_ARB constant, 695 
WGL_BLUE_SHIFT_ARB constant, 695 
WGL_COLOR_BITS_ARB constant, 695 
WGL_DEPTH_BITS_ARB constant, 694 
WGL_DOUBLE_BUFFER_ARB constant, 695 
WGL_DRAW_TO_BITMAP_ARB constant, 694 
WGL_DRAW_TO_WINDOW_ARB constant, 694 
WGL_FULL_ACCELERATION_ARB constant, 696 


WGL_GENERIC_ACCELERATION_ARB constant, 
696 


WGL_GREEN_BITS_ARB constant, 695 
WGL_GREEN_SHIFT_ARB constant, 695 
WGL_NEED_PALETTE_ARB constant, 694 


WGL_NEED_SYSTEM_PALETTE_ARB constant, 
695 


WGL_NO_ACCELERATION_ARB constant, 696 
WGL_NUMBER_OVERLAYS_ ARB constant, 695 


WGL_NUMBER_PIXEL_FORMATS_ARB constant, 
694 


WGL_NUMBER_UNDERLAYS_ARB constant, 695 
WGL_PIXEL_TYPE_ARB constant, 695 
WGL_RED_BITS_ARB constant, 695 
WGL_RED_SHIFT_ARB constant, 695 
WGL_SHARE_ACCUM_ARB constant, 695 
WGL_SHARE_DEPTH_ARB constant, 695 
WGL_SHARE_STENCIL_ARB constant, 695 
WGL_STENCIL_BITS_ARB constant, 694 
WGL_STEREO_ARB constant, 695 
WGL_SUPPORT_GDI_ARB constant, 695 
WGL_SUPPORT_OPENGL_ARB constant, 695 
WGL_SWAP_COPY_ARB constant, 696 
WGL_SWAP_EXCHANGE _ ARB constant, 696 
WGL_SWAP_LAYER_BUFFERS_ARB constant, 695 
WGL_SWAP_METHOD_AREB constant, 695 
WGL_SWAP_UNDEFINED_ARB constant, 696 


WGL_TRANSPARENT_ALPHA_VALUE_ARB 
constant, 695 
WGL_TRANSPARENT_ARB constant, 695 
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WGL_TRANSPARENT_BLUE_VALUE_ARB 
constant, 695 

WGL_TRANSPARENT_GREEN_VALUE_ARB 
constant, 695 


WGL_TRANSPARENT_RED_VALUE_ARB constant, 
695 


wglCopyContext function, 732 
wglCreateContext function, 658, 731 
wglCreateLayerContext function, 731 
wglDeleteContext function, 667, 732 
wg!DescribeLayerPlane function, 733-735 
wglGetCurrentContext function, 736 
wglGetCurrentDC function, 736-737 
wglGetProcAddress function, 73, 693, 873 
wg!MakeCurrent function, 658, 667, 737 
wglShareLists function, 737-738 
wglSwapLayerBuffers function, 738-739 
wglUseFontBitmaps function, 682-684, 739 
wglUseFontOutlines function, 679-681, 739-741 
widgets, 840-841 
width of lines, 104-106, 150 
wiggle functions, 643 
wglCopyContext, 732 
wglCreateContext, 658, 731 
wglDeleteContext, 667, 732 
wglDescribeLayerPlane, 733-735 
weglGetCurrentContext, 736 
wglGetCurrentDC, 736-737 
weglGetProcAddress, 693 
wglMakeCurrent, 658, 737 
wglShareLists, 737-738 
wglSwapLayerBuffers, 738-739 
wglUseFontBitmaps, 682-684, 739 
weglUseFontOutlines, 679-681, 739-741 
winding, 110-111, 237 
windows 
creating, 52, 82, 658, 660-661 
creating with GLX, 800-801 
double-buffered windows, 801 
frameless windows, 685-686 
full-screen windows, 686-689 
scaling, 58, 85 


Windows operating system, 643-644. See also 


wiggle functions 
device contexts, creating, 661-663 
Extended OpenGL, 646-647 
extensions, 690-691 
extended pixel formats, 694 
new entrypoints, 692-693 
simple extensions, 691-692 
WGL extensions, 693-696 
fonts 
2D fonts, 682-684, 739 
3D fonts, 679-681, 739-741 
3D text rendering, 681 
full-screen rendering 
frameless windows, 685-686 
full-screen windows, 686-689 
GDI device contexts, 648-650 
Generic OpenGL, 644 
IDC (Installable Client Driver), 644-645 
MDC (Mini-Client Driver), 645-646 
messages 
WM_CREATE, 663, 667 
WM_DESTROY, 663 
WM_PAINT, 668-669 
WM_PALETTECHANGED, 671 
WM_QUERYNEWPALETTE, 670 
WM_SIZE, 667 
WM_TIMER, 668 
MFC (Microsoft Foundation Classes), 654 
multithreaded rendering, 689-690 
OpenGL rendering context, 657-658 
copying, 732 
creating, 658, 663-666, 731 
current context, returning, 736 
deleting, 663-667, 732 
initializing, 666-667 
making current, 658, 737 
shutting down, 667 
palettes 
3-3-2 palettes, 674-675 
color index mode, 679 
color matching, 669-670 


creating, 670-678 
destroying, 677-678 
determining need for, 673 
LOGPALETTE structure, 673-674 
message handlers, 671-672 
palette arbitration, 670-672 
PALETTEENTRY structure, 674 
restrictions, 678-679 
pixel formats, 650-651 
describing, 651-653 
enumerating, 654-655, 726-729 
extended pixel formats, 694-696 
pixel rendering buffer, 653 
returning, 729 
selecting, 656-657, 725-726 
setting, 656-657, 729-730 
Win32, 662 
Windows 95 Game Developers Kit, 36 
WinMain function, 648, 659-660 
WINRECT program, 648-649 
WM_CREATE message, 663, 667 
WM_DESTROY message, 663 
WM_PAINT message, 668-669 
WM_PALETTECHANGED message, 671 
WM_QUERYNEWPALETTE message, 670 
WM_SIZE message, 667 
WM_TIMER message, 668 
WndProc function, 649 
wrap, texture wrap, 394-395 
writemask, 929 


X-Y-Z 


X servers, 798 

X Window System. See GLX 
X11 libraries, 793-796 
XCreatePixmap function, 826 
XCreateWindow function, 800 
xdpyinfo command, 797 
Xfree86 project, 796-797 

Xi Graphics Summit, 797 


zoom 


Xlib spinning cube program 

bitmap fonts, 812-824 

initial code listing, 801-812 
XLoadQueryFont function, 812 
XMapWindow function, 801 
XNextEvent function, 801 
XOpenDisplay function, 798 
XOR parameter (glLogicOp function), 293 
XPD instruction, 951 
XVisualinfo pointer, 799 


yaw, 195 


z-axis, 29 
zoom, 327-328, 370 
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What’s on the CD-ROM 


The companion CD-ROM contains all of the source code for the book, tools, and OpenGL 
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OpenGL SuperBible, Third Edition is a comprehensive, hands-on 
guide that provides everything you need to program with the 
new version of OpenGL. This newly expanded edition covers 
OpenGL 1.5, OpenGL 2.0’s Shading Language, ARB low-level 
shader extensions, and programming details for Windows®, 
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graphics programming and 3D graphics and seasoned OpenGL 
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manual that can be used time and again. Find the necessary 
guidance in applying complex concepts—such as drawing in 
space; points, lines, and polygons; moving around in space; 
color, lighting, and materials; raster graphics in OpenGL; 
texture mapping; 3D modeling and object composition; fog and 
blending visual effects; curves and surfaces; and more. 
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OpenGL programming in the game design degree program at 
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founder and president of Starstone Software Systems, Inc., where 
he develops multimedia simulation software for the PC and 
Macintosh platforms using OpenGL. 


Benjamin Lipchak develops OpenGL drivers at ATI Research in 
Marlboro, Massachusetts. Formerly writing Digital UNIX and 
Windows NT OpenGL drivers for AlphaStations at DEC and 
Compaq, Benj recently joined ATI to help pioneer programmable 
shader technology. He participated in the OpenGL Architecture 
Review Board standardization of shader extensions and chaired 
the ARB_fragment_program working group. 
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Learn how to: 


* Create three-dimensional objects on your PC 


© Move your objects or yourself around in a 
virtual world 


© Use techniques for fast real-time rendering on 
Windows®, Mac® OS X, and Linux 


* Make use of OpenGL hardware acceleration 
* Create interactive three-dimensional scenes 


© Take advantage of programmable graphics hard- 
ware with the new OpenGL Shading Language 


CD-ROM includes: 


¢ Complete source code for all example programs 
(Windows®, Mac® OS X, and Linux) 


¢ The GLUT Library and RenderMonkey for Windows 


* Demo version of Right Hemisphere’s Deep 
Exploration 


¢ The complete OpenGL specification in Adobe® 
Acrobat® Format 


* Acollection of additional OpenGL example 
programs 


RenderMonkey 


OpenGL Image Operations 


